mdflow MCP Server

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

With no annotations, the description carries full behavioral disclosure burden. It only says the link is 'validated' and avoids 'manual operations,' but gives no details about side effects, failure modes, permissions, or what happens to existing links.

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 and front-loads the core purpose. Minor marketing phrasing like 'in one simple call' could be trimmed, but the structure is economical overall.

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 10 parameters, no annotations, and no output schema, this description is severely incomplete. It explains neither the validation behavior nor the roles of required and optional parameters, leaving an agent with too little to 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?

Schema description coverage is 0% and the description adds no parameter-level meaning. It never mentions sourceId, targetId, kind, label, or any other parameter, leaving all 10 parameters semantically unexplained.

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 operation: connecting two architecture Blocks via a validated Link. It also hints at differentiation by noting this avoids manual operations, though it does not explicitly compare itself to sibling tools like graph_mutate or architecture_link_suggest.

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 creating a validated link between Blocks rather than manually crafting graph mutations. However, it does not state when not to use it or name an alternative tool, leaving some ambiguity among a large sibling set.

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 burden of behavioral disclosure. 'Suggest' and 'based on AST source imports' imply a read-only analysis, but the description never explicitly states that no graph or architecture mutations occur, nor does it mention permissions, side effects, or whether it requires local source files through projectRoot.

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. It states the action, target, and basis efficiently, making it easy for an agent to scan.

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 the core purpose but is incomplete for confident invocation. There is no output schema, no parameter explanations, no mention of what the returned 'links' look like, no guidance on optional parameters, and no clarification of whether the tool modifies anything. An agent would struggle to know how to use taskContextId or includeStructured effectively.

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 names none of the four parameters. It implicitly maps to blockId via 'architecture Block' and hints at projectRoot through 'AST source imports', but it does not explain taskContextId or includeStructured. The description fails to compensate for the schema's complete lack of parameter documentation.

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 'suggest' and identifies the resource ('architectural links for an architecture Block') plus the method ('based on AST source imports and layered conventions'). This clearly differentiates it from siblings like architecture_connect, which would actually apply or connect links rather than merely suggest them.

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 the agent wants candidate architectural links derived from source imports and layering rules. However, it does not explicitly state when not to use it, what alternatives exist, or how it differs from graph_patch, graph_mutate, or architecture_connect beyond the word 'suggest.'

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 burden of behavioral disclosure. It only states the core action ('replace an already-bound AST symbol body') and the exclusion, but does not mention side effects, destructive nature, verification requirements, or any preconditions beyond 'already-bound.' For a mutation tool, this is a significant gap.

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

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

The description is two sentences, front-loaded with the purpose, and the exclusion is placed second. It is efficient with no wasted words. However, it could include a few more useful details without becoming bloated, so it's not a perfect 5.

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 (8 parameters, 4 required, no output schema, no annotations), the description is incomplete. It does not explain the purpose of verifyCommand, expectedSourceHash, or what happens after replacement. It hints at the 'already-bound' precondition but omits critical execution context, making it insufficient for safe invocation.

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

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

Schema description coverage is 0%, and the description provides no explanation of any of the 8 parameters (blockId, symbol, newCode, verifyCommand, etc.). It mentions 'symbol body' but does not map to any parameter or clarify the role of required fields like verifyCommand or expectedSourceHash. The description fails to compensate for the lack of schema documentation.

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

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

The description states a specific verb and resource: 'Replace one already-bound AST symbol body.' It further distinguishes itself by explicitly naming what it is not ('Not a general editor') and routing new symbols, tests, and multi-file edits elsewhere. This makes it clear what this tool does and how it differs 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?

The description gives explicit when-not-to-use guidance: 'Not a general editor: new files, new symbols, tests, and multi-file edits should use the host editor, then source_sync and source_binding_accept.' It names the alternatives and conditions, leaving no ambiguity about when to choose 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 provided, the description carries the full burden. It discloses prerequisites and validates inputs, implying a state-change operation (sealing) that requires verification. However, it does not detail what happens on failure (e.g., if Checkpoint is not fresh), whether the operation is reversible, or what the response looks like. This is moderate transparency for a state-changing 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?

The description is concise at one sentence, but it is densely packed with conditional requirements, making it slightly hard to parse on first read. It front-loads the action and prerequisites, but the syntax is complex. Still, every phrase carries meaning without fluff.

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

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

Given the high parameter count and zero schema coverage, the description is insufficiently complete. It explains the core purpose and prerequisites, but leaves many parameters undefined and doesn't mention failure modes or side effects, which would be critical for a sealing operation that likely finalizes a state.

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

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

Schema description coverage is 0%, so the description must compensate for all 8 parameters, but it only explains the semantics of blockId (implied), executionId (must be a successful receipt), and checkpointId (implied by 'that Checkpoint'). It does not clarify the purpose of actor, reason, projectRoot, taskContextId, or includeStructured, leaving agents to guess or infer.

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 action ('Seal') and the resource ('a verified Block implementation'), and it specifies the completion criteria (valid SourceBindings and a fresh passed Checkpoint). It is distinct from siblings like block_code_mutate or checkpoint_record because it focuses on sealing after verification, not mutating or recording.

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 the conditions for when this tool should be used: when there are valid Current SourceBindings and a passed Checkpoint. It also clarifies the requirement for executionId to be a successful receipt cited by that Checkpoint, which helps an agent decide if it meets prerequisites. While it doesn't name alternatives, the specific conditions provide clear usage 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 carries the burden of disclosing behavior. It explains the default return content and restricts mode=slice, which is useful. However, it does not mention side effects, read-only status, output format, or how the limit-related parameters affect behavior.

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

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

Two sentences with no filler; the main action is front-loaded, the default behavior is summarized, and the mode caveat is placed last. Every sentence contributes 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?

For a tool with 7 parameters, no output schema, and no annotations, the description is too sparse to fully prepare an agent. It misses the meaning of most parameters, any prerequisites, and the shape/limits of the returned stream, making it only partially 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 description coverage is 0%, so the description must compensate for 7 parameters. It only clarifies the mode enum distinction (contract vs slice) and leave chainId, projectRoot, maxTotalChars, taskContextId, includeStructured, and maxLinesPerSymbol unexplained. Most parameters depend entirely on their schema definitions.

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 ('Extract') and names a concrete resource ('contract-first stream along an architectural Chain'), with a list of what the default returns. It is clearly about retrieving code/contract information and is distinct from general graph or planning tools, though it does not explicitly name a sibling alternative.

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 usage guidance within the tool by distinguishing default contract mode from slice mode, but it does not explain when to choose this tool over siblings like project_map, graph_flow, or architecture_link_suggest. The context for using chain_code_stream is implied rather than 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?

With no annotations provided, the description carries the behavioral disclosure burden. It discloses that original history is preserved, that the operation is reversible, and that stale or unsupported changes are rejected rather than partially reverted. This gives meaningful safety and failure semantics, though it does not detail all side effects or permission 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 short and front-loaded with the core action, followed by important safety guarantees. Both sentences add value, and there is no filler or repetition of schema field names. It earns a 4 because it is concise, though a bit more context would be welcome.

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 10 parameters, no output schema, and no annotations, a two-sentence description is not sufficient for reliable invocation. The description covers high-level intent and safety but omits parameter roles, return behavior, and usage context. An agent would likely need additional documentation or examples to call this 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?

The schema has 0% description coverage and 10 parameters, so the description must compensate. It loosely implies the target is a ChangeSet and that only update-only changes are appropriate, but it does not explain the required changeSetId, the optional context fields, or any parameter behavior. Most parameters like task, actor, planId, reason, gitHead, projectRoot, chainScopeId, and taskContextId remain completely unexplained.

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: create a new reverse ChangeSet to revert a ChangeSet. It also adds safety and scope qualifiers ('safe, fully reversible update-only ChangeSet', 'rejected instead of partially reverted'), which clarify the intended operation. It does not explicitly differentiate against sibling tools, but the action and resource are specific enough for basic identification.

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 'for a safe, fully reversible update-only ChangeSet' implies when the tool is appropriate, and 'stale or unsupported changes are rejected' implies a boundary condition. However, it does not explicitly state when to use this tool versus alternatives, nor does it name any sibling tool or give 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?

With no annotations provided, the description carries the behavioral burden. It does explicitly state 'Read only,' which clarifies the safe mutation profile. It also implies incremental behavior via 'after a known change sequence.' However, it does not disclose response format, pagination/limit behavior, error conditions, or what 'mutations' includes, leaving notable 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?

Two sentences, no fluff. The operation is stated first, followed by the usage context. 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?

This is a 6-parameter tool with no output schema and no annotations, yet the description only provides a high-level use case and one parameter hint. It doesn't explain which parameters are needed for common scenarios, what the return payload looks like, or how 'known change sequence' maps to the sequence field. The agent would struggle to invoke it correctly based solely on this description.

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

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

Schema description coverage is 0%, so the description must compensate, but it barely does. The phrase 'after a known change sequence' hints at the 'sequence' parameter, but the other five parameters (limit, projectRoot, taskContextId, includeStructured, sourceSyncRevision) receive no explanation. This is insufficient for an agent to confidently supply correct parameter values.

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 a specific verb and resource: 'Read only graph/checkpoint mutations after a known change sequence.' This makes the core operation understandable. However, it does not explicitly name or differentiate from any sibling tool, only contrasting with 'reloading the project' rather than a specific 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 second sentence gives explicit usage context: 'Use this for live synchronization and compact read-back instead of reloading the project.' This tells the agent when to choose this tool. It stops short of a full 5 because it doesn't mention when not to use it or explicitly compare with siblings like source_sync or timeline_sync.

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 reveals that standalone checkpoints are included by default, which is a useful behavioral detail, and 'List' implies a read-only operation. However, it does not mention pagination, ordering, default filter behavior, or output structure, leaving some uncertainty.

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

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

The description is two sentences with no filler. It front-loads the core action and resource, then adds a practical use case. Every sentence contributes useful 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?

This is a moderately complex tool with 11 optional parameters, no output schema, and no annotations. The description conveys the basic purpose and one inclusion behavior but does not explain the remaining filter semantics, return shape, or defaults. An agent could make a basic call, but would struggle to use the tool confidently for targeted verification workflows.

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

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

Schema description coverage is 0%, so the description must compensate for 11 parameters. It adds meaning for status, target, Plan, and ChainScope filters, but leaves many parameters such as limit, locale, projectRoot, taskContextId, unassignedOnly, and includeStructured entirely unexplained. The compensation is only partial and insufficient for full correct usage.

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 lists checkpoints, a specific resource, and identifies key filtering dimensions: status, target, Plan, and ChainScope. The added note about including standalone checkpoints not referenced by any Plan clarifies an important inclusion edge case, making the purpose specific and useful.

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 says to use this for a compact verification inbox and contrasts it with opening every entity, giving clear context for when it is appropriate. It does not name a sibling alternative like checkpoint_record, but the use-case guidance is direct and actionable.

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 burden. 'Create or update' discloses an upsert mutation, and 'with evidence' hints at a requirement. But for a tool with 23 parameters, complex behavior is undisclosed: optimistic concurrency (expectedRevision), invalidation semantics (invalidatedAt), aggregation behavior (aggregationPolicy), and evidence-level requirements (requiredEvidenceLevel) are all silently present in the schema yet never surfaced in the description.

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

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

Two sentences with no filler — efficient and front-loaded with the action. However, the concision comes at the cost of substance: the second sentence ('Passed checkpoints are the only basis for healthy completion states') conveys philosophy rather than actionable behavior. For a tool with this parameter count, the brevity reflects under-specification rather than disciplined pruning.

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?

Completely inadequate for the tool's complexity: 23 parameters, nested objects (evidence, aggregationPolicy), six enums, and no output schema. The agent is left without knowledge of the status enum semantics, targetType meaning, checkpointKind distinctions, or the return format. Nothing in the description compensates for the absence of an output schema or the massive parameter surface.

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

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

Schema description coverage is 0%, so the description must compensate — and it barely does. It maps to only two parameters: 'evidence' (the evidence array) and 'passed' (a status enum value). The other 21 parameters, including required targetType, targetId, title, and the six enums, receive no clarification. The description adds marginal value over the schema for a tool that badly needs 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 verb+resource: 'Create or update a checkpoint with evidence.' This distinguishes it from sibling checkpoint_list (listing) and checkpoint_refresh_candidates (refreshing candidates). The second sentence adds useful domain significance about passed checkpoints. However, it doesn't explicitly differentiate itself from the other checkpoint siblings by name or scoping condition.

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 on when to use this tool versus checkpoint_list or checkpoint_refresh_candidates. No alternatives are named, and no exclusions or preconditions are given. The 'passed checkpoints are the only basis' sentence hints at domain semantics but doesn't tell the agent when to record a checkpoint versus read candidates or list checkpoints.

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 the behavioral burden. It discloses that it does not auto-pass and maps changed bindings, which is useful. However, it does not mention side effects (if any), prerequisites (e.g., existence of an execution receipt), or what the output contains. The mention of 'recorded execution receipt' is vague without more context. It adds some transparency 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?

Two sentences with no waste. The main purpose is front-loaded, and the clarifying note about not auto-passing is concise. 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 tool with 4 parameters, no output schema, and no annotations, this description is insufficient. It lacks parameter explanations, prerequisite conditions (like having a recorded execution receipt), and any indication of the return format or structure. The description gives a general sense but not enough for an agent to invoke the tool correctly without further inference.

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

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

Schema description coverage is 0% and the description does not explain any of the four parameters (executionId, projectRoot, taskContextId, includeStructured). The agent must rely solely on parameter names, which are technical and not self-explanatory. The description provides zero guidance on parameter meaning or optionality, so it fails to compensate for the schema 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 states a specific verb and resource ('List stale checkpoints') and immediately clarifies what it does not do ('Does not auto-pass checkpoints'), distinguishing it from sibling tools like checkpoint_record or checkpoint_list. It also explains the mechanism ('maps changed bindings onto retest_required items'), giving a clear, non-tautological purpose.

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 after a 'recorded execution receipt' and clarifies it is not for auto-passing checkpoints, but it does not explicitly name alternative tools or conditions for when to use this vs. others. There is no 'use this when X, use Y when Z' guidance, only a negative constraint. The context is present 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?

With no annotations, the description carries the full behavioral burden. It does disclose that output is Markdown, budgeted, and that refs should be expanded selectively, but it does not describe output shape, budget semantics, or any side effects or prerequisites.

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 front-loaded sentences with no repetition or filler. The first sentence delivers the core operation and the second adds a targeted usage rule; 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?

Eight parameters with zero schema descriptions, no annotations, and no output schema make this description insufficient for reliable invocation. It provides a starting point and usage stage, but leaves most parameter decisions and behavioral expectations 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 0%, so the description must compensate. It only hints at semantics through 'budgeted' and 'selected refs' and never explains required 'task', focusRefs, budgetChars, projectRoot, locale, or includeStructured.

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 first sentence names a specific action ('Get'), a concrete deliverable ('budgeted Markdown context pack'), and a scope ('current development task'), so a model can tell what the tool produces. It does not explicitly contrast with siblings like project_map or plan_context, so it falls just short of full differentiation.

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?

'Use at task start' gives an explicit temporal trigger, and 'expand only selected refs' is a concrete usage instruction. There is no mention of when not to use it or which sibling tools should be preferred.

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 burden and does well by disclosing that this is a compact index and that bodies, rationale, alternatives, and consequences are intentionally omitted. It also names the tools that do include those details. It does not discuss side effects, but 'Read' strongly signals a non-mutating operation.

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 the core action and resource front-loaded and no filler. Every clause adds useful information: scoping, omission details, and routing to alternatives.

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 clearly explains what the tool returns and what it does not, and it directs users to the right alternative for full records. However, with no annotations, no output schema, and entirely undocumented parameters, the definition lacks enough detail about how includeStructured, locale, and taskContextId affect the result.

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 provides no property descriptions (0% coverage), and the description does not explain locale, projectRoot, taskContextId, or includeStructured. The phrase 'project-scoped' loosely hints at projectRoot but is far from enough for an agent to select and populate parameters correctly.

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 ('Read') and resource ('compact project-scoped Decision index'), then explicitly states what is omitted and points to alternatives for one record. This clearly distinguishes the tool from decision_open and entity_open.

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 says to use decision_open or entity_open(type=decision) when full decision records are needed, which gives both a when-to-use and when-not-to-use signal. This is clear routing guidance with named 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 are provided, so the description bears the full burden of behavioral disclosure. It mentions what information is returned (a compact history) but does not disclose potential side effects, read-only nature, error conditions, or any special behavior such as authorization requirements. This is a significant gap for a tool with no annotation safety hints.

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 efficient and front-loads the core action ('Open one architecture Decision') before listing the return contents. It is not verbose profile, but it does pack the key purpose into a compact form. It loses a point because the list of return items is a bit of a catalog, but overall it is 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?

The tool has six parameters, but only a required id is self-evident. The description explains the return type but not the meaning of `historyLimit`, `includeStructured`, `taskContextId`, or `locale`. Since there is no output schema and no annotations, the description leaves significant gaps for an agent to call the tool correctly with optional parameters. It is minimally viable but not 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 description coverage is 0%, so the description must compensate for the six parameters galaxy. However, the description only clarifies the return content, not the parameters like `historyLimit`, `includeStructured`, or `locale`. It adds minimal semantic value beyond the schema, which already has types and, for some, clear names. Given the 0% coverage, the description does not do enough to explain the parameters' purpose, so a 3 is generous but reflects the basic clarity of `id` as the required identifier.

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 opens a single architecture Decision and lists the specific content returned (rationale, alternatives, consequences, scope, supersession, history). This is a clear verb+resource, and it distinguishes itself from the sibling `decision_list` by specifying the singular open action, though it does not explicitly contrast with 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 the tool is for viewing a single decision, but it does not explicitly say when to use it vs `decision_list` or other tools. The context of 'Open one architecture Decision' suggests a point-in-time read, but there is no guidance on when to prefer this over listing or searching. It is adequate but lacks explicit usage 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?

With no annotations present, the description must explain behavior itself. It does disclose that output is narrowed to 'only relevant details and recent History,' which is useful, but it does not clarify whether 'Open' is a pure read operation, what side effects may occur, or what the response shape is.

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; the core action and entity scope appear first. It is concise, but the brevity comes at the cost of omitting important behavioral and parameter detail, so it is efficient rather than comprehensive.

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?

With no annotations, no output schema, and zero parameter descriptions, the description is the only source of guidance, and it is too thin. An agent cannot confidently determine what 'relevant details' means, how history is limited, or how optional parameters like includeStructured and projectRoot affect the call.

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 covers 7 parameters with no descriptions, and the description only weakly maps to them: 'one Block, Chain, Link, Plan, or Decision' relates to 'type', and 'recent History' hints at 'historyLimit'. Params like locale, projectRoot, id, and includeStructured are left unexplained, so the description does not compensate for the 0% schema coverage.

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 ('Open') and clearly states the object: one Block, Chain, Link, Plan, or Decision. It also conveys the scoped nature of the operation ('only relevant details and recent History'), but it does not explicitly distinguish this tool from siblings like decision_open, which may overlap in purpose for decisions.

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 on when to choose this tool over siblings such as decision_open or timeline_view, and no context about appropriate use cases or prerequisites. The description merely states what the tool does without helping an agent decide between 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?

With no annotations, the description carries the behavioral disclosure burden. It does well by enumerating the created artifacts: atomic checkpoints, PlanChanges, dependency-ordered steps, integration gates, and an acceptance gate, and it notes the operation happens 'in one transaction.' It does not mention idempotency, overwrite behavior, or permissions, but the disclosure is substantial.

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 core purpose is front-loaded and the sentence contains no filler. It is dense and uses a semicolon to pack a lot of behavior into one sentence, but it remains appropriately sized for the complexity it communicates.

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 ten parameters, no schema descriptions, no annotations, and no output schema, the description is insufficient for an agent to reliably construct a valid invocation. It explains the domain behavior well but leaves the input contract almost entirely undocumented.

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 provides no parameter-level guidance. None of the ten parameters such as goal, actor, reason, taskContextId, includeStructured, or requiredEvidenceLevel are explained, so an agent cannot determine what values to pass or how they affect the generated plan.

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: 'Generate one Foundation Plan from every non-deprecated unimplemented Block.' It clearly scopes what the tool does and distinguishes it from the architecture-only create_block behavior, so an agent can tell this apart from related plan/block operations.

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 explains that this is for explicit implementation/verification Plans and contrasts itself with 'plain architecture-only create_block.' This gives useful selection context, though it stops short of an explicit if-then rule such as 'use create_block when only architecture modeling is needed.'

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 the full burden of disclosing side effects. It says the tool 'creates or updates links,' but it does not explain overwrite behavior, reversibility, permissions, or what happens to existing links. For a mutating graph tool, this is a significant transparency gap.

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

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

The description is two sentences with no filler: the first states purpose and gives examples, the second states the core behavior and value. It is front-loaded and 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 six parameters, no output schema, and no annotations, the description is incomplete for safe autonomous invocation. An agent can craft a flow string but remains uncertain about optional parameter meanings, update side effects, and return behavior.

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 required 'flow' parameter is helpfully explained with natural-language syntax examples. However, schema description coverage is 0%, and the other five parameters (actor, reason, projectRoot, taskContextId, includeStructured) are left undefined beyond their names. The description does not compensate for this 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 uses a specific verb ('Declare'), names the resource ('architectural flows and pipelines'), and provides concrete DSL examples that make the tool's function unmistakable. It also contrasts itself with JSON-based graph mutation, helping distinguish it from siblings like graph_mutate and graph_patch.

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 arrow-expression examples ('block:A -> block:B -> block:C') clearly illustrate how to use the tool, and the phrase 'declare architectural flows and pipelines' states the intended context. However, it does not explicitly say when to prefer this over alternatives or when not to use it, leaving some routing 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?

With no annotations, the description carries the behavioral disclosure burden. It reveals atomicity, that Decisions are not Canvas Blocks and never enter Block/Chain/Plan coverage, the architecture-only nature of a plain create_block, valid link kinds, and the expectedRevision requirement for updates. It omits details about delete consequences and authorization, but still goes well 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 four sentences and front-loads the core verb and resource list before adding targeted caveats. Every sentence adds semantic value with no filler or repetition of the schema structure. It is dense but 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?

Given the high complexity—10 parameters, 34 action enum values, no output schema, and no annotations—the description provides useful guidance for common create/checkpoint cases but is not complete. It does not explain top-level parameter semantics, return/response shape, or the behavior of destructive operations. It is adequate but has clear 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 0%, and the description only partially compensates. It meaningfully explains operation-level fields such as create_block vs create_checkpoint, link kinds, and expectedRevision, but leaves most top-level parameters (reason, planId, gitHead, projectRoot, chainScopeId, taskContextId, includeStructured) unexplained. For a tool with 10 parameters, this is a significant 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 opens with 'Atomically create or patch' and lists the concrete resources involved: Blocks, Decisions, Links, Chain paths, Plans, Checkpoints, scopes, and source refs. This clearly states the tool's function and scope. It does not explicitly differentiate it from the sibling graph_patch, 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?

The description provides useful in-tool guidance: use create_checkpoint in the same ChangeSet when a check is necessary, keep calls small, and provide expectedRevision for updates. However, it does not state when to prefer graph_mutate over graph_patch or other sibling tools, and it lacks explicit when-not-to-use conditions.

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 transparency burden. It does disclose useful behavior: expansion into an atomic ChangeSet, preservation of omitted fields, and optional atomic Block checkpoint creation. However, it omits any direct mention of mutation scope, destructiveness, permissions, or failure behavior, so transparency is adequate but not complete.

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 tightly packed sentences with no filler. The core action is front-loaded, and every clause adds a distinct and useful fact: patch format, atomic ChangeSet equivalence, partial-update behavior, and checkpoint capability.

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 10 parameters, no annotations, and no output schema, the description is too sparse for confident invocation beyond the required patch. It explains the patch concept well but does not cover the remaining parameters, return values, or failure modes, leaving an agent with significant uncertainty for valid optional usage.

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 clarifies the required patch format (mdflow/1 Markdown-like). The other nine parameters—task, actor, planId, reason, gitHead, projectRoot, chainScopeId, taskContextId, and includeStructured—are left entirely unexplained, and checkpoint=auto is mentioned even though it is not present in 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 opens with a specific verb and resource: 'Apply a compact mdflow/1 Markdown-like patch.' It also distinguishes graph_patch from the sibling graph_mutate by noting it expands into the same atomic ChangeSet, so an agent can tell the tools apart without inspecting their schemas.

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 frames this tool as the compact Markdown-patch variant of graph_mutate and mentions the atomic ChangeSet equivalence, giving an agent a clear context for when to use it. It does not explicitly list exclusions or say 'use graph_mutate instead when...', so it stops 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?

With no annotations, the description carries the behavioral disclosure burden. It does reveal one useful trait—does not load the entire project—which suggests a read-only, performance-conscious operation. However, it does not explicitly confirm read-only behavior, permissions, response formats, or possible error cases, leaving gaps for a no-annotation 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?

The description is a single concise sentence that front-loads the core purpose and the key qualifier. Every word contributes value, with no repetition or 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?

Despite a clear purpose, the tool has 8 parameters, no output schema, and no annotations. The description does not explain return values, parameter syntax, required setup like projectRoot/taskContextId, or how search results are structured. For a tool of this complexity, the description is far too skeletal to enable reliable invocation.

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

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

Schema description coverage is 0% across 8 parameters, and the description provides no parameter-level meaning. Parameters like kinds, states, includeStructured, projectRoot, and taskContextId are left entirely unexplained, forcing an agent to guess their roles and formats.

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

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

The description states a specific verb ('Search') and resource ('graph entities and source paths'), and adds a distinguishing performance qualifier ('without loading the entire project'). This clearly separates it from mutation siblings like graph_mutate or graph_patch, even though those siblings are not named.

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 guidance is given about when to use this tool versus alternatives. The phrase 'without loading the entire project' implies a lightweight search use case, but no alternative tools are mentioned and no exclusion criteria are provided. An agent must infer usage from the tool name and siblings.

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 burden. It implies a read-only safety profile via 'Inspect,' and it lists the kinds of status information returned (drift, blocks, gates). However, it does not disclose output shape, whether any live computation triggers side effects, or typical cost/performance 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 a single efficient sentence with no filler. The main action and resource are front-loaded, and the list of inspectable aspects is compact. It earns high marks for brevity, though the dense enumeration slightly reduces 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 four optional parameters, zero output schema, and no annotations, the description alone is insufficient. It fails to explain what parameters to supply, how results are returned, or what distinguishes this status snapshot from related tools. An agent cannot confidently invoke it correctly based on this definition alone.

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

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

Schema description coverage is 0%, and the description does not mention any of the four parameters (locale, projectRoot, taskContextId, includeStructured). It provides no compensation for the schema's lack of parameter descriptions, leaving an agent to guess what each field is for.

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 ('Inspect') and identifies the resource as 'project architecture health' plus four concrete aspects (drift, isolated blocks, ghost blocks with code, verification gates). This makes the tool's purpose clear and distinctive, though it does not explicitly differentiate from sibling tools like graph_validate or graph_search.

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 on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or preferred conditions, and the sibling list contains closely related tools (graph_validate, graph_search) with no contrast 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?

With no annotations, the description must carry the full burden. 'Validate' implies a read-only checking operation, but the description does not disclose side effects, permissions, output format, or failure behavior, leaving the agent unable to predict what invoking the tool will do beyond running checks.

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

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

The description is a single dense sentence with no filler; the main verb is front-loaded. However, the long list of capitalized domain terms is compressed to the point of ambiguity, slightly hurting 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?

The tool has no annotations, no output schema, 0% schema parameter coverage, and many siblings, yet the description only lists validation subjects. It lacks the usage, parameter, and output information an agent needs to select and call this 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?

Schema description coverage is 0% and the description never maps projectRoot, taskContextId, or includeStructured to the validation concepts it lists. An agent cannot determine what values are appropriate for these parameters from either the schema or the description.

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 clear action ('Validate') against a specific set of graph, plan, and contract references, which separates it conceptually from mutation/search siblings like graph_mutate and graph_search. However, the comma-separated object list is jargon-heavy and does not clarify what a successful validation means or returns.

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 call this tool instead of graph_search, graph_flow, or architecture_connect, nor any exclusion criteria. The context signals show a large sibling group, so the absence of routing information is a notable gap.

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 behavior disclosure. It does a solid job by naming three specific transformations (strips ANSI, collapses compiler stdout, isolates stack traces) and the rationale (preventing token flooding). It does not mention return format, potential loss of information, or side effects, but the core behavior is transparent enough.

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 deliver the purpose, specific behavior, and rationale without redundancy. The key verb and resource are front-loaded, and every phrase adds value. This is an appropriately sized and 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?

The tool has six parameters, no output schema, and no annotations, yet the description explains only the general purpose. It leaves critical usage details unstated, such as what each parameter controls, what the return value looks like, and whether the tool mutates inputs or produces a new sanitized string. For an agent to invoke it correctly with full parameter awareness, this is insufficient.

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 hints at 'rawOutput' implicitly. It does not explain exitCode, maxChars, projectRoot, taskContextId, or includeStructured. An agent could infer rawOutput but would have no guidance for the other five parameters, especially maxChars and includeStructured, whose semantics are not obvious from names alone.

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 ('Sanitize') plus a clear resource ('build, test, or terminal command outputs'), and enumerates concrete actions: strips ANSI noise, collapses routine compiler stdout, isolates actionable stack traces. This makes the tool's purpose unmistakable and distinct from any sibling tool in the 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?

The description clearly states the intended input type ('build, test, or terminal command outputs') and the goal of protecting the context window, which implies when to use it. However, it does not explicitly mention alternatives or when not to use it. There are no sibling sanitization tools, so the context is strong enough for a 4 rather than 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?

With no annotations, the description carries the full behavioral disclosure burden. It discloses the output shape (hierarchical document with ChainScopes, changes, gates, source refs) and the 'compact' nature, implying read-only behavior via 'Read.' It does not mention truncation effects from maxChars, error conditions, or permission requirements, leaving some behavioral 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 tight sentences. The first enumerates the returned content in a compact list, and the second states usage priority without any filler or redundancy. It is front-loaded with the verb and resource.

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 tool with no output schema and no annotations, the description covers the core behavior and usage timing well. But with 6 parameters, it leaves important context unexplained, such as what includeStructured does, how maxChars affects output, and what taskContextId/projectRoot are used for. It is 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?

Schema description coverage is 0%, so the description must compensate. It provides useful domain context for what a 'Plan' is, which gives meaning to the id parameter. However, it does not explain locale, maxChars, projectRoot, taskContextId, or includeStructured; these remain semantically opaque despite visible schema defaults and enums.

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: 'Read one Plan as a compact hierarchical development document.' It enumerates the exact content (overview, ChainScopes, Block/Link/Chain changes, checkpoint gates, exact source refs), which clearly differentiates it from siblings like context_for_task or chain_code_stream. The final sentence, 'This is the primary read before implementing a Plan,' reinforces its distinct 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 gives clear timing guidance: use this before implementing a Plan, and calls it the 'primary read.' However, it does not name alternative tools or state when NOT to use this tool, so it falls short of fully explicit exclusion 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 provided, the description carries the behavioral burden. It clearly signals a read-only operation via 'Read' and discloses a useful performance behavior: it does not load entity bodies. It does not discuss permissions, rate limits, or potential staleness, but for a read-only map tool this 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?

The description is a single well-structured sentence that front-loads the core action and resource, then lists the map's contents without unnecessary words. Every clause adds information about what the tool provides.

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 overview tool with all parameters optional, the description adequately explains the return contents and the lightweight nature of the call. However, with no output schema and no parameter explanations, the agent still lacks guidance on how 'includeStructured', locale, or taskContextId affect the result—so this is only minimally 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 description coverage is 0%, and the description adds no parameter-level meaning. Params like 'includeStructured' and 'taskContextId' are left entirely unexplained, forcing the agent to guess their purpose. The description must compensate for the sparse schema and does not.

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 ('Read') and a specific resource ('compact project map'), then enumerates exactly what the map contains: architecture coverage, ordered Plans, Chain paths, integration gates, and source-sync status. It also distinguishes itself from entity-level tools by stating it does so 'without loading entity bodies'.

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

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

The description gives clear context for when to use this tool: when the agent needs a compact, cross-cutting project overview rather than detailed entity contents. It does not explicitly name alternative tools or state when not to use it, so it stops 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?

With no annotations, the description carries full burden and explicitly states the side effect scope ('creates only .mdflow/project.json') and idempotency. It does not mention failure modes, but the disclosed behavior is precise and helps an agent anticipate the tool's mutation footprint.

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 short sentences front-load the core operation, then add one precise behavioral detail; 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 is insufficient to determine how to populate the non-required fields or what includeStructured controls. It covers the basic projectRoot use case but not the full call surface.

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 input schema has no property descriptions and the description adds no meaning for id, name, or includeStructured; only 'existing directory' hints at projectRoot. This leaves the optional parameters semantically opaque.

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 concrete verb ('Register') plus a specific resource ('an existing directory as an mdflow project') and names the exact output artifact, .mdflow/project.json. This clearly differentiates it from sibling tools by scope and outcome.

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 conveys when to use it: for an existing directory that should become an mdflow project, and the idempotence note tells the agent it can be re-run when the descriptor already exists. It does not name alternatives or explicit when-not-to-use conditions, so not 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?

No annotations exist, so the description carries full burden. It usefully discloses that output is redacted and compressed and that raw stdout/stderr is suppressed — genuinely valuable behavioral context. But it never discloses that running a command can mutate the filesystem (or its destructive potential), which is a significant omission for a command-execution 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?

Two lean sentences with the core purpose first and the unique return contract second — no filler. It is efficient, though for an 8-parameter tool additional structured detail (e.g., a parameter summary) would have been warranted while still staying concise.

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 (8 parameters, no output schema, no annotations), the description is far from complete. It omits all parameter semantics, expected output structure, and side-effect disclosure, leaving an agent without enough information to invoke the tool correctly beyond the command string.

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% with 8 parameters, and the description explains none of them. It does not clarify cwd, projectRoot, timeoutMs, maxChars, executionKind, taskContextId, or includeStructured. The redaction/compression wording hints at maxChars but never explicitly maps to parameters, so the description fails to compensate for the schema 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?

Description states a specific verb (Run), resource (project-local command), and the return shape (redacted, compressed terminal summary). It explicitly claims raw stdout/stderr never enters the response, which distinguishes it from process-launching siblings and grounds its role as a command gateway.

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 names concrete use cases ('tests, builds, and mutation verification'), giving the agent context on when to invoke it. However, it does not state when NOT to use it or name an alternative tool, so routing against siblings like block_code_mutate or chain_code_stream is left implicit.

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 statement that 'Every candidate is re-resolved against current source before a SourceRef is created' discloses a non-obvious internal behavior, which is valuable because there are no annotations. But with zero annotation coverage, the description still omits important transparency details such as what happens when re-resolution fails, whether persistence is atomic or partial, and any permission or mutation implications.

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

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

The description is two sentences with no filler. The primary purpose is front-loaded and the second sentence adds an important behavioral caveat. Every word earns its place, and no part is redundant given the schema already contains parameter types and constraints.

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?

This is a mutation/persistence tool with no annotations and no output schema, so the description carries the full context burden. It fails to cover several needed details: what happens if a candidate does not match the current source, whether operation is transactional, the meaning of includeStructured, and what the tool returns or confirms. The description is too sparse for a tool with this many 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?

Schema description coverage is 0% and the large majority of the 7 parameters are not mentioned. Only 'AST source binding candidates' and 'a Block' loosely point to bindings and blockId; actor, reason, projectRoot, taskContextId, and includeStructured have no semantic explanation in the description, leaving an agent to guess their roles.

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 action ('Persist'), the target resource ('AST source binding candidates for a Block'), and the transformation ('SourceRef is created'). It implicitly distinguishes from the sibling source_binding_suggest via 'explicitly selected' and 'Persist', but it never names that sibling or another alternative, so it falls just short of full differentiation.

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 'explicitly selected ... candidates' implies the tool should be used when a user has already chosen binding candidates, and the re-resolution note sets a precondition. However, the description gives no explicit when-to-use or when-not-to-use guidance and never references sibling alternatives such as source_binding_suggest.

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?

There are no annotations, so the description carries the burden. It explicitly discloses the read-only nature of the tool, which is the most important behavioral default. It does not mention response shape, staleness, or failure behavior, but the core side-effect profile is handled clearly.

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

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

Two sentences, no fluff, and critical guidance is front-loaded.

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

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

Defines the operation's role and read-only nature, and pairs it with the accept sibling nicely. However, with no output schema, the agent is left without knowing what a suggestion looks like, and unclear params (includeStructured, taskContextId) reduce completeness.

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

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

With 0% schema description coverage, the description must compensate. It doesn't explain parameters like taskContextId, includeStructured, limit, or maxFiles beyond their namesaren't self-sufficient. The phrase 'from AST symbols and project semantics' provides thematic context but not parameter-level meaning.

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—'Suggest source bindings for a Block'—and clarifies the input domain ('from AST symbols and project semantics'). It also distinguishes the tool from source_binding_accept by explicitly naming the sibling as the persistence step. An agent can tell exactly what this tool does and what it is not.

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 usage guidance: suggestions are read-onlyaint, and if you want to commit an explicitly chosen candidate you should use source_binding_accept. This clearly separates the tool from its sibling and tells the agent when not to use it.

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

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

With no annotations, the description bears the full behavioral disclosure burden. It meaningfully discloses that source content is intentionally not loaded into the response and that the output categorizes bindings as moved, changed, missing, or ambiguous plus affected Blocks/Chains. This goes beyond a generic scan description, though it omits side-effect or permission details, which are likely irrelevant for a read-only scan.

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 exceptionally concise: two sentences, with the key non-loading behavior front-loaded and the report contents delivered in a compact clause. Every word earns its place and no filler 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?

With five undocumented optional parameters, no annotations, and no output schema, the description is not complete enough for confident invocation. It gives a high-level summary of what the tool reports but leaves the agent unclear about which parameters are relevant for a given scenario, how to interpret the bindings output, and how the tool fits into the larger workflow. The absence of any parameter guidance is a significant gap.

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

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

Schema description coverage is 0%, so the description must compensate for explaining the five parameters, but it does not. 'Scan current files' only loosely hints at projectRoot, and nothing clarifies sinceRevision, includeUnchanged, includeStructured, or taskContextId. The description provides domain context but no parameter-specific semantics, leaving the agent to guess from names alone.

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 ('Scan') and resource ('current files for bound symbols'), and clearly distinguishes the tool's purpose from a generic file read by stating it does not load source into the response. It reports binding status and affected Blocks/Chains, making the purpose understandable. It does not explicitly differentiate itself from sibling tools, 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?

The description implies usage when one needs to detect moved, changed, missing, or ambiguous symbol bindings in current files. However, it gives no explicit guidance on when to choose this tool over siblings like timeline_sync, changes_since, or graph_validate, and no conditions for using it. This is implied usage, not explicit task-selection 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 carries the full disclosure burden. It does disclose the key side effects—automatic progress update and nowDoing pointer change—beyond a bare 'advance step' statement. However, it does not address status options, reversibility, or what happens when the step is already complete.

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, and the primary action and automatic side effects are front-loaded. It earns its place and is easy to parse.

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, this short description is not enough for correct invocation. It omits parameter roles, allowed status behavior, and return value expectations.

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

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

Schema description coverage is 0%, so the description must compensate. It maps conceptually to stepId and nextStepId and hints at progress/status, but leaves planId, summary, projectRoot, taskContextId, includeStructured, and the status enum meanings unexplained. An agent cannot reliably populate 8 optional parameters from this text.

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 ('Advance') and resource ('active step of a Plan') and names concrete outcomes: marking complete, updating progress, and moving nowDoing to the next step. This clearly distinguishes it from sibling plan tools such as plan_context and timeline_sync.

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 use case: when a step in a Plan has been accomplished and the active pointer should move on. It gives no explicit exclusions, prerequisites, or alternatives, so an agent must infer that this is the right action versus a broader plan mutation 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 burden of behavioral disclosure. It does disclose that the tool mutates nowDoing, nextUp, and the active step, and mentions the cross-conversation scope, but it omits side effects, whether values are overwritten, idempotency, required scoping fields, or return behavior.

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 with no filler, and the core action is front-loaded. It earns its place, though it could add a usage note 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?

The tool has 9 optional parameters, no annotations, and no output schema, yet the description provides almost no context for how to invoke it correctly or what happens when optional parameters are omitted. This is far from complete for a fairly complex sync operation.

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

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

Schema description coverage is 0%, so the description must compensate, but it only clarifies nowDoing and nextUp, with 'active step' loosely mapping to stepId. Parameters like planId, projectRoot, taskContextId, touchedFiles, lastFinished, and includeStructured are inadequately explained.

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 action ('Synchronize'), a specific resource ('development cursor and active focus across conversations'), and lists the concrete fields it updates (nowDoing, nextUp, active step). This clearly separates it from siblings like timeline_view (viewing) and source_sync (source code).

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 guidance about when to use this tool versus alternatives such as step_advance, timeline_view, or source_sync, and no when-not-to-use conditions. The 'across conversations' phrase implies a use case, but the agent is left to infer 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?

With no annotations, the description does state a key behavior (read-only) and lists what the returned timeline contains. However, it does not disclose how results are scoped by projectRoot or taskContextId, what includeStructured changes, or any assumptions about which timeline is 'unified.'

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 contains the verb, the resource, and the three key output groups without filler. It is front-loaded and every clause adds 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 gives a good sense of the response content, but no output schema exists and parameter behavior is undocumented, so the overall calling context is incomplete. An agent cannot confidently know what happens when only some parameters are passed or what includeStructured toggles.

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

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

Schema description coverage is 0% and the description does not explain projectRoot, taskContextId, or includeStructured. While the names hint at their roles, includeStructured is genuinely ambiguous and there is no guidance on optionality or default behavior.

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 ('Read') and a precise resource ('the unified project Timeline'), then lists distinguishing contents: execution phases, P0/P1/P2 ordered plans, and active cursor fields. This makes it easy to separate from write/sync siblings such as timeline_sync and step_advance.

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 read-only intent is clear, but the description never states when to choose this over related tools or when not to use it. An agent must infer from the verb 'Read' and the tool name that this is the inspection path; no explicit alternatives or exclusions are given.

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