lxDIG MCP

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

With no annotations provided, the description carries full weight. It discloses conflict detection, the required parameters, and that the tool returns a claimId. It does not discuss side effects like claim duration or locking behavior, but core behaviors are well described.

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

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

The description is concise with five short sentences. It is front-loaded with purpose, then conflict detection, then required params, return value, and enum list. No unnecessary words; every sentence adds value.

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 7 parameters and no output schema. The description covers the two required params and the enum for claimType, but omits purpose for optional params and does not describe the response structure beyond claimId. Given the complexity, the description is incomplete for fully informed use.

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

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

The input schema has 100% parameter description coverage, so the description only adds marginal value. It explains 'targetId' as file path or task ID, 'intent' as natural language, and lists 'claimType' enum values. However, it ignores optional parameters like 'taskId', 'agentId', 'sessionId', and 'profile', which remain documented only 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 clearly states the tool's purpose: 'Claim a file, function, task, or feature for exclusive editing.' It uses a specific verb ('Claim') and resource types, and distinguishes from siblings like 'agent_release' by explaining the conflict detection mechanism.

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 usage context: it explains conflict detection and instructs to save the claimId for the matching 'agent_release' call. However, it does not explicitly state when not to use this tool or mention alternatives beyond 'agent_release'. The guidance is clear but not exhaustive.

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 but only states 'release an active claim'. It does not disclose what 'release' entails, such as side effects, reversibility, or state changes.

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?

Extremely short but at the cost of missing essential information. While concise, it does not fully earn its place due to lack of detail.

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 3 parameters, no output schema, and no annotations, the description is lacking. It omits behavioral context, prerequisites, 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 coverage is 100%, so baseline is 3. Description adds no additional meaning beyond the parameter descriptions; e.g., 'outcome' and 'profile' are not contextualized for the release action.

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 uses specific verb 'Release' and resource 'active claim', clearly indicating the action. It distinguishes from siblings like 'agent_claim' and 'agent_status' through the unique action, though no explicit differentiation is provided.

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 alternatives. The description does not specify prerequisites, conditions, or when not to use it.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the purpose without detailing side effects, authentication requirements, rate limits, or whether it modifies data. The schema hints that omitting agentId lists all agents, but this is not explicitly communicated 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?

The description is a single, efficient sentence with no wasted words. It immediately conveys the tool's core function, which is appropriate for a simple retrieval tool.

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

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

Given the tool's low complexity (2 parameters, no output schema), the description covers the basic purpose. However, it omits usage context and behavioral details, leaving gaps for an agent deciding whether to invoke the tool. The mention of 'active claims and recent episodes' provides some return-value context, but it is minimal.

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

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

Schema description coverage is 100%, providing clear parameter meanings (agentId optional, profile with enum). The description adds overall context ('for an agent') but does not elaborate on parameter specifics beyond what the schema already offers. Thus, it meets the baseline of 3.

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

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

The description 'Get active claims and recent episodes for an agent' uses a specific verb ('Get') and identifies the resource ('active claims and recent episodes') and target ('agent'). It clearly distinguishes the tool from siblings like 'agent_claim' (which likely deals with individual claims) and 'agent_release'.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as when to use 'agent_claim' or 'episode_add'. It lacks context about prerequisites, scope (e.g., user's own agents vs. any agent), or exclusion criteria.

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

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

No annotations are provided, so the description fully bears the burden of behavioral transparency. It clearly states that the tool returns a recommended path, layer, and rationale, and it specifies required inputs (name, type) and optional dependencies. It does not mention side effects, but the tool appears to be a read-only suggestion.

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 unnecessary words. It front-loads the purpose and succinctly covers parameters and output.

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 simplicity, no output schema, and 100% schema coverage, the description is complete. It explains inputs, what is returned (path, layer, rationale), and the tool's role.

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

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

Schema coverage is 100%, but the description adds value by providing examples ('e.g. UserService') and explicitly listing the enum values for 'type'. It also clarifies that 'dependencies' are imports the new element will use, which is not fully captured in the schema 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 clearly states the tool's purpose: 'Suggest the best file path and layer for a new code element.' It uses a specific verb ('Suggest') and resource ('file path and layer'), and the tool is distinct from siblings like arch_validate or graph_query.

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 lists required and optional parameters but does not provide guidance on when to use this tool versus alternatives (e.g., arch_validate). No exclusion criteria or context is given.

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

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

Discloses return format (violations list and statistics), scoping behavior, and strict mode effect. Without annotations, more context on whether the tool is read-only, authorization needs, or performance implications would be beneficial. The description does not cover these aspects.

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

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

Three concise sentences, each adding distinct value: purpose, scoping behavior, and strict mode effect. No redundancy or fluff. Front-loaded with the primary action.

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 simplicity (2 optional params, no output schema), the description covers the key aspects: purpose, return type, and parameter usage. Missing details about rule definitions and error handling, but overall sufficient for an agent to use the tool correctly.

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

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

The schema descriptions are minimal ('Files to validate', 'Strict validation mode'). The description adds value by explaining that omitting files validates the full project and that strict=true elevates warnings to errors, providing practical meaning beyond the schema.

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

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

The description clearly states it checks code files against architecture layer rules and returns a violations list and statistics. While it doesn't explicitly differentiate from siblings like arch_suggest or contract_validate, the verb 'validate' and focus on rules conveys a distinct 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?

Provides concrete usage patterns: call with no files for full project validation or with a list of file paths to scope. Also explains the strict parameter effect. Does not explicitly mention when not to use or alternatives, but the guidance is clear.

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

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

No annotations provided, so description must carry this burden. It only states 'Find' without disclosing whether this is a read-only operation, what it returns, or any side effects. Insufficient for an agent to judge safety.

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

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

Single sentence is concise but lacks structure and important details. Falls on the side of under-specification rather than efficient 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?

No output schema exists, so description should explain what 'blocking issues' means and what response format to expect. It does neither, leaving the agent guessing about the tool's output and usage context.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds no additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

Description clearly states verb 'Find' and resource 'blocking issues'. However, it does not differentiate from sibling search tools like 'semantic_search' or 'graph_query', missing specificity.

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 alternatives. No context on prerequisites or typical scenarios 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. It discloses the dependence on Qdrant embeddings and mentions the clustering factors, but lacks details on side effects, performance, or handling of edge cases (e.g., empty results). It does not contradict any annotations.

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

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

The description is extremely concise: two sentences that front-load the primary action and purpose. Every sentence adds value, with no fluff or repetition.

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

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

Considering the tool has 3 parameters, no output schema, and no annotations, the description provides sufficient high-level context: what the tool does, what it returns, and its dependencies. It is complete enough for an AI agent to understand its functionality, though explicit output structure would improve 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?

Schema coverage is 100% (all parameters described). The description only adds minor context for the 'type' parameter (enum values) and restates the schema's information for 'count' and 'profile'. No additional meaning is provided beyond what the schema already conveys.

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 ('Cluster code elements') and the methodology ('by directory proximity and vector similarity'), specifying the required type parameter and the output (clusters with member counts and samples). It differentiates from siblings like 'find_similar_code' by focusing on clustering, not mere similarity 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?

The description explains the use case ('useful for understanding module boundaries and finding groups of related code'), providing clear context. However, it does not explicitly mention when not to use this tool or suggest alternative tools (e.g., 'semantic_search' for individual queries).

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 burden. It adds 'with dependency context' as behavioral context, indicating the tool considers dependencies. However, it does not disclose whether the tool is read-only, requires permissions, or produces side effects. For a basic explain tool, this is adequate but not comprehensive.

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

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

Description is a single, front-loaded sentence with no wasted words. It could be improved by adding a brief example or clarifying the meaning of 'dependency context', but it is efficient.

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

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

With a simple 2-parameter schema and no output schema, the description is minimal. It does not describe the return value or format of the explanation. While adequate for a straightforward tool, it leaves the agent to infer outputs.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema's field descriptions. The schema describes 'element' and 'depth' clearly, though 'depth' as 'Analysis depth' remains vague.

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 clearly states verb (explain) and resource (code element) with qualifier (dependency context), distinguishing it from sibling tools like find_similar_code or impact_analyze. However, it doesn't specify the format or level of detail of the explanation.

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 on when to use this tool versus alternatives, such as when dependency context is not needed or when to use find_similar_code instead. Usage is only implied by the description.

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

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

No annotations provided, so description carries full burden. It mentions the retrieval method (PPR-ranked) but does not disclose behavioral traits such as whether it is read-only, authorization needs, or side effects. Basic purpose is conveyed but lacks depth.

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, clear sentence that efficiently conveys the tool's purpose and method without any fluff or redundant 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?

With 7 parameters and no output schema, the description fails to explain the output format (e.g., structure of the briefing) or how to use parameters like 'profile'. The complexity is high, but the description does not provide sufficient contextual 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?

Schema description coverage is 100%, so the description adds no extra meaning beyond the schema. The description does not elaborate on parameters like 'task', 'taskId', or 'profile', remaining at baseline value.

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 'Build' and resource 'single-call task briefing' with a clear method 'PPR-ranked retrieval across code, decisions, learnings, and blockers'. It clearly distinguishes itself from sibling tools like decision_query or episode_recall by offering a consolidated briefing.

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 on when to use this tool over siblings. While it implies use for a comprehensive task briefing, it does not state alternatives or when not to use it, leaving the agent with no decision support.

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

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

With no annotations, the description carries full burden. It mentions normalization and validation but does not disclose side effects, return behavior, error handling, or whether the tool is read-only. This is insufficient for safe invocation.

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 waste. It is concise and front-loaded, but could benefit from a bit more detail without becoming verbose.

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

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

Given no output schema and no annotations, the description is inadequate. It does not explain what the tool returns, what normalization entails, or what happens on validation failure, leaving critical gaps for correct utilization.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds minimal extra meaning ('before execution') beyond what is in the schema, earning a baseline score.

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-resource pair: normalizing and validating tool argument contracts. This distinguishes it from siblings like arch_validate, which is about architecture validation. However, it could be more specific about what 'contracts' means in this context.

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

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

No guidance is provided on when to use this tool versus siblings. It does not mention prerequisites, alternatives, or scenarios where this tool should be avoided, leaving the agent to infer 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?

No annotations are provided, so the description must fully disclose behavioral traits. It only says 'view', implying read-only, but does not explicitly state if it is safe, what side effects occur, or any costs. No mention of authentication, rate limits, or how conflicts are determined.

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

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

The description is a single sentence that is concise and front-loaded with the purpose. It contains no fluff, though it could benefit from slight expansion to cover usage without losing conciseness.

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 that there is no output schema and only one parameter without explanation of its variants, the description is insufficiently complete. It tells what the tool does but omits how to interpret responses (e.g., what 'stale claims' means) and lacks guidance on parameter choices.

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

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

Schema coverage is 100% for the single parameter 'profile', so the schema already defines it. The description adds no additional meaning about the profile values (compact, balanced, debug) or when to use each, so it adds no value beyond schema.

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

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

The description clearly states 'Fleet-wide claim view' specifying the verb (view) and resource (claims). It distinguishes from siblings like agent_claim (individual claims) by indicating the scope is fleet-wide and includes active claims, stale claims, and conflicts.

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 an overview of claims but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. Among siblings, no comparative advice is given.

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 supplied, and the description does not disclose behavioral traits such as whether the tool is read-only, idempotent, or has side effects. It does not mention authentication, rate limits, or what triggers the query.

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, short sentence with no wasted words. It is appropriately concise but could benefit from a bit more detail without harming conciseness.

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 six parameters, one required, and no output schema, the description is insufficient. It does not explain what 'decision episodes' are, how results are returned, or how to interpret the response. This leaves the agent with significant ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions. It does not clarify how parameters relate to the query or their semantic 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 states the action 'Query' and the resource 'decision episodes' for a target topic, which distinguishes it from some siblings like progress_query. However, it lacks explicit differentiation from similar query tools such as ref_query or episode_recall.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description solely states the action without contextual usage advice.

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 must carry full behavioral disclosure. It fails to indicate if the tool is read-only, safe, or any side effects, leaving significant ambiguity.

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

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

Single sentence front-loads the core action and resource, with no wasted words. Highly 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?

With 4 parameters, no output schema, and no annotations, the description is too brief. It lacks explanation of what 'temporal graph changes' entail, how anchors work, and what the output is.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional semantic value beyond the schema's parameter descriptions.

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

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

The description clearly specifies the action 'summarize temporal graph changes' and the allowed anchor points (txId, timestamp, git commit, agentId), making it distinct from sibling tools like semantic_diff.

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 by listing anchor types, but does not provide when-to-use or when-not-to-use guidance, nor does it mention alternatives among 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?

No annotations are provided, so the description carries the full burden. It discloses important behaviors: required params, conditional requirement for DECISION, and the effect of the 'sensitive' flag. It does not mention side effects or permissions, but the core behavioral constraints are well covered.

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

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

The description is concise and well-structured. It starts with the main purpose, then lists required fields, important conditional notes, and optional fields. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (10 params, nested objects, no output schema), the description thoroughly explains all parameters and constraints. It covers required, conditional, and optional fields, making the tool easy to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it clarifies that 'entities' are related file/symbol names, 'outcome' values are success/failure/partial, and 'sensitive' excludes from default recalls. This adds value for the agent.

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

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

The description clearly states the tool's action: 'Persist a structured episode in long-term agent memory.' It specifies the required parameters (type and content) and optional ones, effectively distinguishing from its sibling tool 'episode_recall' which is for reading.

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 required fields and when to use the tool. It provides critical guidance for the DECISION type, noting that metadata is required and omitting it returns an error. It could be improved by explicitly mentioning when not to use (e.g., if reading is intended), but the contrast with 'episode_recall' is implied.

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 fully disclose behavior. It mentions three relevance axes but omits any behavioral traits (e.g., no side effects, performance implications, authorization needs, or limitations like result pagination). The description is insufficient for an agent to understand operational context.

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

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

The description is a single, concise sentence that quickly communicates the core function. It is front-loaded and avoids redundancy, though it could be slightly expanded to improve completeness without losing conciseness.

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 8 parameters and no output schema, yet the description is too brief to explain what episodes are, how recall works across the three relevance dimensions, what the response contains, or how to effectively use filters (agentId, taskId, types, entities). It lacks sufficient context for a complex retrieval tool.

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

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

Schema description coverage is 100%, but parameter descriptions are minimal (e.g., 'Recall query', 'Agent filter'). The main description adds no additional parameter context (e.g., format of 'since', meaning of 'types'). Since coverage is high, baseline 3 is appropriate; the description does not significantly augment the schema.

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

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

The description uses a specific verb 'Recall' and identifies the resource 'episodes' and three relevance dimensions (semantic, temporal, entity). This distinguishes it from siblings like semantic_search (which likely targets documents) and graph_query (which targets graph structures), though the term 'episode' is not defined.

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

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

No guidance is provided on when to use episode_recall vs. alternative tools such as semantic_search or graph_query. There is no mention of prerequisites, contraindications, or complementary tools.

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

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

With no annotations, the description carries full burden. It only states the operation without disclosing side effects, authentication needs, or error behavior. The simple 'get' implies read-only, but this is not explicit.

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 wasted words. It is clear and to the point, though slightly more context could be added without harming conciseness.

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 lack of output schema and simple parameter set, the description is minimally complete. It does not explain return values, error cases, or relationships to sibling tools, leaving the agent with insufficient context for effective invocation.

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

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

The input schema covers 100% of parameters with descriptions, so the description adds no additional meaning beyond what is already in the schema. The baseline score of 3 applies.

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

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

The description 'Get feature implementation status' clearly states the action (get) and resource (feature implementation status). It is specific and distinguishes from sibling tools like 'agent_status' or 'progress_query' by focusing on features, though it doesn't explicitly differentiate.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'progress_query' or 'status' tools. There are no context signals or explicit when/when-not instructions.

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

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

No annotations are provided, so the description carries full burden. It discloses behavioral traits such as requiring a search string and having different detection modes. However, it does not mention side effects, authorization needs, or rate limits, which are not necessarily critical for this non-destructive 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, front-loaded sentence that immediately states the core purpose, followed by necessary details. Every sentence is substantive, with no redundancy 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?

Given no output schema, the description could inform the agent about the return format or what kind of results to expect. It sufficiently covers parameters and purpose but lacks completeness regarding output, which is a gap for an agent deciding whether to invoke this tool.

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

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

Schema coverage is 100%, providing base descriptions. The description adds value by giving concrete examples for 'pattern' and explaining each enum value for 'type', aiding interpretation beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: 'Find architectural patterns or violations in code.' It uses specific verbs and resources, and distinguishes from siblings by focusing on detection of patterns/violations like circular dependencies, unused files, etc.

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 explains when to use the tool by specifying required 'pattern' and optional 'type' with enumerated detection modes. Although it does not explicitly mention when not to use or name alternative tools, the examples and mode descriptions provide clear context for appropriate usage.

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

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

No annotations provided, so the description carries full burden. It discloses the vector similarity method and return fields (names, file paths), but lacks information on permissions, side effects, or rate limits. Adequate but not comprehensive.

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

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

Two clear, front-loaded sentences covering purpose, required parameter, optional settings, and return type. No redundant words; 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?

Covers key aspects: what it does, required input, optional parameters, and output description. However, it does not explain the profile parameter or detail the output structure beyond 'names and file paths', leaving some gaps for a 4-parameter tool with 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 coverage is 100%. The description adds meaningful context for elementId (source and type) but merely repeats defaults for threshold and limit, and omits the profile parameter entirely. Baseline 3 applies; marginal added value.

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 verb 'Find' and the resource 'code elements similar to a given function or class', specifying the method 'by vector similarity'. This distinguishes it from sibling tools like semantic_search (query-based) and find_pattern (pattern matching).

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 instructions: requires elementId from graph_query or code_explain, not a symbol name. However, it does not mention when not to use this tool or suggest alternatives among siblings.

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

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

No annotations are present, so the description must fully disclose behavior. It only states the tool 'reports' health/freshness, but does not describe side effects, required permissions, response format, or any limitations. This is insufficient for an AI agent to understand its full impact.

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 wasted words. However, it could be restructured to front-load key information and potentially include brief usage context without losing conciseness.

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 output schema, so the description should explain what the report contains (e.g., fields returned, format). It does not. Additionally, with many sibling tools, context signaling when to use this vs others is missing, making the description incomplete for effective tool selection.

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 sole parameter 'profile' already has a description and enum values in the input schema (100% coverage). The description adds no additional semantic detail beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Report' and clearly identifies the resource as 'graph/index/vector health and freshness status'. This distinguishes it from sibling tools like graph_query (which queries the graph) or graph_rebuild (which modifies it).

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

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

No guidance is provided on when to use this tool versus alternatives. For example, there is no mention that it should be used before graph_query to verify graph readiness, or that it is a read-only diagnostic 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?

No annotations exist, so the description must disclose behavioral traits. It does not mention side effects, mutability, auth requirements, or performance. While a query is likely read-only, the description omits this explicit assurance.

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 clearly communicates the core purpose. It is front-loaded and efficient, though a second sentence with usage nuance could improve without harming conciseness.

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 (7 parameters, 3 enums, no output schema), the description is too sparse. It does not explain key choices like mode, limit, or projectId, nor does it describe the return format. An agent would need more context to use it 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 100%, so the baseline is 3. The description adds no extra meaning beyond 'Cypher or natural language', which is already implied by the parameters. No additional context about parameter interaction or interpretation is provided.

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 executes Cypher or natural language queries against the code graph, which is a specific action on a distinct resource. It mentions two query types, distinguishing it from other graph-related tools. However, it could be more explicit about differentiation from siblings like 'ref_query'.

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

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

No guidance is provided on when to use this tool versus alternatives. With many sibling tools (e.g., sematic_search, ref_query), the lack of usage recommendations or exclusions leaves the agent without decision support.

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

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

No annotations provided, so description must cover behavioral traits. It fails to disclose side effects (e.g., overwrites existing graph), required prior setup, or execution characteristics. This is a critical 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 single-sentence description is too short given the tool's complexity (8 parameters). It lacks structure and key information, making it under-specified rather than 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?

Without output schema or annotations, the description should provide more context about rebuild behavior, input requirements, and outcomes. It is insufficient for an 8-parameter tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds no extra meaning beyond schema for parameters like mode, verbose, etc.

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 'Rebuild code graph from source' states the verb and resource, but is vague about what 'rebuild' entails. It does not differentiate from sibling tools like graph_health or graph_set_workspace.

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 alternatives (e.g., incremental vs full rebuild, or when to use graph_health). The description does not mention prerequisites or typical use cases.

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

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

No annotations are provided, so the description must fully convey behavioral traits. It only states the basic purpose without describing side effects (e.g., persistence, scoping, reset behavior) or requirements like authentication or thread safety.

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, which is concise and front-loaded. However, it sacrifices necessary detail on usage and behavior, making it somewhat under-specified.

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 5 optional parameters and no output schema, the description lacks completeness. It does not explain what 'active' means, how context is managed, or the tool's effect on other operations, leaving gaps for an agent.

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

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

All parameters have descriptions in the schema (100% coverage). The tool description adds no additional meaning beyond the schema, so it meets the baseline but does not enhance understanding.

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

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

The description clearly states the tool sets the active workspace/project context for subsequent graph tools. It uses a specific verb ('Set') and resource ('workspace/project context'), and distinguishes it from sibling graph tools that perform queries or rebuilding.

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 this tool should be used before other graph tools by saying 'for subsequent graph tools'. However, it does not explicitly state when to use it versus alternatives or when not to use it, which would improve clarity.

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?

Without annotations, the description carries full burden but fails to disclose behavioral traits. It does not state whether the tool is read-only, whether it modifies state, or what the output format is. This is a critical 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?

While the description is short, it lacks a clear structure and fails to front-load key information. It is under-specified rather than concise, omitting necessary details for correct usage.

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 4 parameters, no output schema, and many sibling tools, the description is completely inadequate. It does not explain what 'impact of changes' means, the context of use, or how to interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add any extra meaning beyond the schema's parameter descriptions, which are already minimal. No improvement over 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 'Analyze impact of changes' clearly indicates a verb and a resource, but it is vague and does not differentiate from sibling tools like arch_suggest or code_explain which also analyze aspects of 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?

The description provides no guidance on when to use this tool versus alternatives such as arch_validate or semantic_slice. No context about prerequisites or exclusions is given.

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 takes on full disclosure duty. It explains indexing creates graph nodes and edges, and supports incremental mode. However, it does not mention whether the operation is destructive or requires permissions, which is a notable 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?

Two concise sentences with key information front-loaded. No unnecessary words, and each sentence adds value: first states purpose and scope, second adds behavioral detail and output edges.

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

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

Given no output schema, the description adequately covers what the tool produces (graph nodes and edges). It lacks details on prerequisites, error handling, or return values, but with high schema coverage, it is mostly complete for its complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates the incremental parameter and embedding option but does not add meaning beyond the schema's own descriptions. Thus, no extra value.

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 explicitly states the tool discovers and indexes markdown documentation files into graph nodes, listing specific file types (README, ADRs, etc.) and the output edges. This clearly differentiates it from sibling tools like search_docs or graph_query.

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

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

The description mentions incremental mode but does not provide explicit guidance on when to use this tool versus alternatives like graph_rebuild. There is no when-not or comparison to siblings, leaving the agent to infer 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?

No annotations are provided, so the description carries the full burden. It clearly explains the three distinct behaviors (workspace context, graph rebuild, file generation) and conditions ('if not present'). It does not disclose potential side effects like overwriting existing files or permission requirements, but for an initialization tool that is expected to set up state, this is reasonable.

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 extremely concise: two sentences that deliver purpose and usage with no waste. It is front-loaded with the most critical information first.

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 6 parameters, full schema coverage, and no output schema, the description adequately covers the tool's purpose and usage. It lacks mention of return format or error behavior, but for a setup tool the actions are more important. Still, a slight gap exists.

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

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

Schema coverage is 100%, meaning all 6 parameters already have descriptions. The tool description adds some overall context tying parameters to actions (e.g., 'workspaceRoot' for setting context, 'rebuildMode' for rebuild), but does not provide additional semantic details beyond what the schema already offers. Therefore, baseline 3 is appropriate.

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

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

The description specifies the verb 'initializes' and the resource 'project', enumerating three concrete actions: setting workspace context, triggering graph rebuild, and generating copilot instructions. It distinguishes from sibling tools like graph_rebuild or setup_copilot_instructions by combining them into a one-shot operation.

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

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

The description explicitly states when to use it: 'as the first step when onboarding a new project or starting a fresh session.' It does not explicitly list alternatives or when not to use it, but the context implies that for single actions like only rebuilding the graph, one would use graph_rebuild.

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

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

The description discloses that the tool returns task/feature nodes with status, assignee, and due date, implying a read-only operation. However, it does not explicitly state that no data is modified, and there are no annotations to supplement. For a query tool, this is adequate but not outstanding.

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 very concise, comprising two sentences that front-load the purpose and quickly cover usage and output. Every sentence adds value with no redundancy.

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

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

The description covers input and output sufficiently for a simple query tool, especially given the lack of output schema. However, it omits details on error handling, empty results, or limits. In context with many sibling tools, more usage differentiation would improve 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?

The schema descriptions cover all parameters, but the tool description adds value by providing example query strings and clarifying the status enum values. The profile parameter is not mentioned, but the examples for query and status are helpful. Given high schema coverage, the description goes beyond baseline.

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 tasks or features by status. It specifies the verb 'list', the resource 'tasks or features', and the filtering by status. It is specific and not a tautology.

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

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

No guidance is provided on when to use this tool versus sibling tools like feature_status or blocking_issues. The description does not mention scenarios where this tool is preferred or when to avoid 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 provided, the description carries the full burden but only states the action. It does not disclose side effects, permissions, state changes, or output characteristics, which are critical for a synthesis 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 with no wasted words. However, it is arguably under-specified for the tool's complexity, but conciseness is still good.

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 4 parameters and no output schema, the description lacks key details about the synthesis process and output format. It does not explain what 'reflections and learning nodes' entail or how they are returned, leaving significant gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema; parameters are already documented concisely 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 clearly states the verb 'synthesize' and the resource 'reflections and learning nodes from recent episodes'. It distinguishes this tool from siblings like episode_recall or episode_add by focusing on synthesis rather than recall or addition.

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 on when to use this tool versus siblings. The description does not mention prerequisites, exclusions, or alternatives, leaving the agent to infer context.

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

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

With no annotations, the description carries the full burden. It states the tool queries a repo on the same machine, implying a read-only operation, but does not disclose error handling, permissions, or behavior for invalid repo paths. The disclosure is moderate but lacks detail.

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

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

The description is two sentences—concise and front-loaded with the action. Every word earns its place, with no redundancy or 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?

The description covers the main purpose and use context, but given the 6 parameters and no output schema, it lacks details about return format, behavior with different modes, or error conditions. Adequate but not comprehensive.

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

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

Schema description coverage is 100%, so the schema adequately documents each parameter. The description adds no additional parameter-level meaning beyond the high-level purpose. Baseline 3 is appropriate.

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

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

The description clearly states it queries a reference repository on the same machine for architecture insights, design patterns, conventions, or code examples. It distinguishes from sibling tools (e.g., semantic_search, find_pattern) by focusing on an external repo rather than the current workspace.

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 indicates it is useful 'for borrowing context from a well-structured sibling repo when working on the current workspace,' providing a use case. However, it does not explicitly state when not to use this tool or mention alternatives among sibling tools, leaving the agent to infer.

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

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

No annotations provided, so description carries burden. It describes read-only search behavior and return structure, but does not mention error handling or behavior when index is empty. Adequate but not fully transparent.

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

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

Two concise sentences: first describes action and result, second notes prerequisite. No redundant information, but could be slightly more streamlined.

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

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

Covers major aspects: what it searches, how (query/symbol), what it returns (fields), and prerequisite. Lacks order/relevance details and pagination, but sufficient for a search tool with clear 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 coverage is 100%, but description adds value by stating query and symbol are mutually exclusive and explaining symbol lookup via DOC_DESCRIBES edges. This goes beyond schema descriptions.

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

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

Description clearly states the tool searches indexed documentation sections by full-text or symbol name, and lists return fields. It distinguishes from sibling tools like index_docs (prerequisite) and semantic_search (different search type).

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 prerequisite 'Run index_docs first to populate the index' and implies use case. Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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 explains that the tool compares graph metadata and not source-code semantics or embedding similarity, and it describes the return format (changed property keys and left/right-only properties). However, it does not explicitly state whether the tool is read-only, has side effects, or requires authentication. The behavioral context is adequate but incomplete.

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

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

The description is three sentences long, front-loaded with the primary purpose, followed by usage guidance and a clarifying note. Every sentence adds value; there is no redundancy or unnecessary information. It is highly concise and well-structured.

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

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

Given the tool has three parameters, no output schema, and no nested objects, the description covers the essential: purpose, parameter source, and return type. It explains what the tool does, how to input, and what to expect. However, it does not describe the output structure in detail (e.g., format of property keys), which would be helpful but is not critical given the tool's simplicity.

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

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

Schema coverage is 100%—all three parameters have descriptions. The description adds crucial context beyond the schema: it explains that elementId1 and elementId2 should be from graph_query or code_explain results, not symbol names. This is a meaningful addition that helps the agent select correct values. The profile parameter is not elaborated, but the schema provides enum choices.

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

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

The description clearly states the tool's purpose: 'Compare graph-stored metadata properties between two code elements.' It specifies the resource (graph metadata), the verb (compare), and includes necessary context (requires element IDs from specific sources). This distinguishes it from sibling tools like diff_since (source code diff) and find_similar_code (embedding similarity).

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 explicit guidance on how to obtain the required element IDs: 'use the id fields from graph_query or code_explain results (not symbol names).' It implies when to use (when comparing metadata properties) and implicitly distinguishes from sibling tools that handle source code diffs or similarity. However, it does not explicitly state when not to use 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?

No annotations are provided, and the description only states the tool performs a search, implying it is read-only. It lacks disclosure of any behavioral traits such as rate limits, caching, or result ordering.

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 very concise at one sentence, which is appropriate for a simple search tool. However, a bit more information could be included without being verbose.

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 4 parameters, no output schema, and no annotations. The description does not explain return values, result format, or how the profile parameter affects output. This is insufficient for an agent to fully understand the tool's behavior.

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

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

Schema description coverage is 100%, with each parameter having a basic description. The tool description adds no additional meaning beyond the schema, maintaining the baseline score of 3.

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

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

The name and description clearly indicate the tool performs semantic search on code using vector similarity. However, it could be more specific about the scope of code searched and does not differentiate from sibling tools like 'find_similar_code' or 'search_docs'.

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 alternatives. The description is a single statement without context or exclusions, leaving the agent to infer usage from the name alone.

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

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

No annotations provided, so description carries full burden. It mentions optional dependency and memory context but does not disclose side effects, read-only nature, or prerequisites. Agents lack critical behavioral cues.

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

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

Single sentence with key information front-loaded. No waste, but the phrasing 'relevant exact source lines' is somewhat vague. Still concise 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?

With 6 optional parameters including enums for context and profile, and no output schema, the description is too brief. It does not explain modes like 'signature', 'body', 'with-deps', 'full', or the profile options, leaving agents underinformed.

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

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

Schema coverage is 100%, so schema already documents parameters. The description adds minimal extra meaning beyond 'optional dependency and memory context'. Baseline 3 is appropriate.

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

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

Describes returning exact source lines with optional context, clear verb+resource. However, it does not explicitly differentiate from siblings like semantic_search or code_explain, missing a chance to improve selection.

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 over alternatives. With many sibling tools dealing with code, the absence of usage context is a significant 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?

No annotations provided, so description carries full burden. It explains the files generated and mentions on-demand reading to avoid context saturation, but lacks details on side effects, permissions, or analysis scope.

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?

Description is concise and front-loaded with the main action in two sentences. However, it lacks structure like bullet points or clear separation of file purposes.

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

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

Given no output schema and no annotations, the description adequately conveys what the tool creates and the rationale for the guide file. It lacks some behavioral details but is sufficient for a setup tool.

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

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

Schema coverage is 100% with each parameter described. Description does not add meaning beyond the schema; baseline of 3 is appropriate.

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

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

The description clearly states the tool analyzes a repository and generates two specific files with distinct purposes. It implicitly distinguishes from sibling tools, which are mostly analysis/query tools, by being a setup tool.

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

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

No explicit guidance on when to use this tool vs alternatives, prerequisites, or scenarios for using the parameters. The description only states what the tool does without 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?

No annotations are provided, so the description carries the full burden. It discloses the return information (suggested test names, types, coverage gaps) but does not explicitly state whether the tool is read-only, safe, or has any side effects. The non-destructive nature can be inferred, but should be explicit.

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

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

The description consists of two sentences with no unnecessary words. The first sentence states the purpose and key requirement, the second describes the output. It is front-loaded and efficient.

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

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

Given three parameters, no output schema, and no annotations, the description covers the essential aspects: required input source, return content, and the fact that suggestions are based on structure and existing tests. A minor gap is the lack of detail on the limit and profile parameters' effects, but these are covered in the 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 coverage is 100%, so the baseline is 3. The description adds value by clarifying that elementId must be the id field from graph_query or code_explain, which is not evident from the schema description ('Code element ID'). For limit and profile, no extra description is added, but they are adequately described 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 states the tool's main action ('Suggest test cases for a code element') with a specific verb and resource. It also clarifies the required input format (elementId from specific tools) and what it returns (test names, types, coverage gaps), leaving no ambiguity about the tool's 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 clearly explains the prerequisite for using this tool: the elementId must come from graph_query or code_explain, not a symbol name. This gives context on when to use it. However, it does not explicitly differentiate from sibling tools like test_select or test_categorize, nor state when not to use it.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states that the tool updates status and optional fields, but does not disclose side effects, idempotency, permissions, rate limits, or response behavior. This is insufficient for a mutation tool.

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

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

The description is two sentences, front-loading the verb and resource, then detailing requirements and optional fields. No superfluous content, earning its place efficiently.

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 7 parameters and no output schema, but the description fails to explain return values, error handling, or validation behavior. This is a significant gap for a mutation tool, leaving the agent underinformed about what to expect after invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some semantic value by specifying that taskId comes from progress_query results, providing status examples, and clarifying notes as progress notes/blockers. However, it does not deeply elaborate parameter usage beyond the schema.

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

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

The description clearly states 'Update the status of a tracked task,' specifying the verb (update) and resource (task). It distinguishes from sibling tools like progress_query (query only) and agent_status (agent status), making the purpose unambiguous.

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 advises using the tool after completing or blocking a task to keep delivery state current, which provides clear when-to-use guidance. It also notes that taskId comes from progress_query results. However, it does not explicitly mention when not to use or 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. The description does not disclose whether the tool is read-only, modifies tests, or returns a categorization. Essential behavioral traits are missing, making it hard for an agent to understand side effects.

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

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

The description is a single sentence and front-loaded, but it is too brief to be minimally adequate. Conciseness is achieved at the expense of informativeness.

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 lack of output schema and the presence of multiple sibling tools with similar names, the description is insufficient. It does not explain what categorization entails or how the output is structured, leaving the agent unsure of the tool's value.

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

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

Schema description coverage is 100% for the single parameter 'testFiles', which has a basic description. The tool description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description states the tool categorizes tests by type, providing a clear verb and resource. However, it is vague about what 'type' means and does not distinguish from sibling tools like test_select or suggest_tests.

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 alternatives such as test_run or test_select. The description implies a specific categorization task but lacks explicit usage context or prerequisites.

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, and the description only repeats 'Execute test suite' without disclosing any behavioral traits (e.g., side effects, permissions, outputs). This is essentially a tautology.

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 wasted words. It is appropriately concise, though lacking in substance.

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 2 parameters and no output schema, the description is too minimal. It fails to explain return values, behavior when tests run, or error handling, leaving significant gaps.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning beyond what the schema provides, leading to a baseline score of 3.

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

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

The description 'Execute test suite' uses a specific verb 'Execute' and resource 'test suite', clearly distinguishing it from sibling tools like 'suggest_tests' or 'test_select'.

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 alternatives like 'test_select' or 'suggest_tests'. No exclusions or context provided.

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

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

No annotations are provided, so the description must carry the full burden of disclosing behavior. It only states 'Select tests' without indicating if this is a read-only operation, what side effects exist, or how the selection algorithm works (e.g., dependency analysis). The parameter 'mode' suggests different behaviors, but the description does not explain them.

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 front-loaded and contains no extraneous information. It is appropriately concise for the tool's simplicity.

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 lack of output schema and the presence of related sibling tools, the description is incomplete. It does not specify the return format (e.g., list of test names, set of files), nor how it integrates with other tools like 'test_run'. The description is minimal, leaving agents to infer essential details.

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

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

Schema coverage is 100% with both parameters having descriptions. The description adds no new semantics beyond the schema; it merely restates the overall purpose. For high coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Select') and resource ('tests affected by changed files'). This differentiates it from sibling tools like 'test_run' (runs tests) and 'test_categorize' (categorizes tests).

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 there are changed files and the user wants to determine which tests are affected, but it does not explicitly state when to use this tool versus alternatives like 'suggest_tests' or 'impact_analyze'. No exclusions or context are provided.

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

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

With no annotations, the description carries full burden. It discloses that the tool lists all tools and their availability, and groups them by category. This provides clear behavioral traits beyond the name.

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 with no wasted words. It is front-loaded with the core action, making it efficient and 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?

The tool is simple with one optional parameter and no output schema. The description covers the basic purpose but does not explain the output structure or how the 'profile' parameter affects results, leaving some ambiguity for the agent.

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

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

Schema coverage is 100%, so baseline 3. The description does not add extra meaning to the 'profile' parameter beyond what the schema already provides, but the mention of 'grouped by category' adds context for output, not parameters.

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

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

The description clearly states the action (list all MCP tools), the resource (tools and their availability), and the grouping (by category). It distinguishes from siblings because siblings are the tools being listed.

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 vs. alternatives. The description does not provide contextual cues or exclusions for other tools.

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