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

No annotations provided, so the description carries full burden. It only states the action (adds tasks) without disclosing side effects, permissions, idempotency, or whether existing tasks are affected.

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 a clear prefix and no unnecessary words. Efficient and front-loaded.

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

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

The tool is simple with a rich schema, but the description lacks any mention of return values or post-conditions. No annotations or output schema details are provided, leaving some 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 coverage is 100% with descriptions for both parameters and nested properties. The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description clearly states the tool adds a list of tasks to the project backlog, using a specific verb and resource. It distinguishes itself from sibling tools like update_task, complete_tasks, and search_tasks.

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

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

No explicit when-to-use or alternatives mentioned. Usage is implied by the tool's purpose, but without guidance on when not to use it versus update_task or complete_tasks.

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 atomicity and auto-unblocking, which are key behavioral traits beyond what annotations would provide (none given). However, it omits other important details like whether the operation is reversible, required permissions, or the response format. The presence of an output schema helps, but the description could be more thorough.

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

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

The description is a single, well-structured sentence. It front-loads the tool category ('[TASK TOOLS]') and then states the precise action. No extraneous information 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?

Given the tool's complexity (mutating with side effects), the description is minimally adequate. It mentions atomic closure and unblocking but lacks context on usage, prerequisites, or outputs beyond what the output schema may provide. The high schema coverage partially compensates, but more detail 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 description coverage is 100%, with each parameter having a clear description (e.g., 'Project name', 'List of task keys to complete'). The tool description adds no further parameter-specific meaning, 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 clearly states the tool's action: 'Atomically closes one or more tasks and auto-unblocks dependents.' This distinguishes it from sibling tools like update_task (which modifies task fields) and add_tasks (which creates new tasks). The verb 'closes' and resource 'tasks' are specific.

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 update_task or when not to use it. It does not mention prerequisites or context for usage, which is a notable gap given the number of sibling 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 provided, the description fully discloses behavioral traits: deletion is immediate and not automatically reversible, returns a confirmation string, and raises a 404 error if path doesn't exist. All critical behavioral aspects are covered.

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

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

The description is concise with meaningful structure: action statement first, then usage guidelines, then return/error info. Every sentence adds value without redundancy. Appropriate length for a simple deletion tool.

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

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

Given the tool's simplicity (2 required string params, no annotations, with output schema), the description is complete. It covers the action, side effects, usage context, return value, and error condition. No missing elements for effective use.

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

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

Schema coverage is 100% with descriptions for both parameters ('Path to delete' and 'Project name'). The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate. No further parameter details are needed.

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 deletes a single artifact file from artifact storage, with the prefix '[ARTIFACT TOOLS]' and clear verb+resource. It differentiates from sibling tools like move_project_artifact and restore_project_artifact.

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: suggests checking backup history before deletion via list_artifact_history, warns against using for move/rename by naming move_project_artifact as alternative, and mentions restoring via restore_project_artifact. This clearly indicates when and when not to use.

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

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

With no annotations, the description effectively conveys the tool's read-only nature through 'Retrieves' and 'outline'. It discloses the token-optimization and depth behaviors, and mentions the summary_only parameter's condition. It could mention potential errors or scope limits, but for a retrieval tool it is sufficient.

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 three sentences that front-load the purpose, then provide usage guidance. 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 moderate complexity (4 parameters, all documented), the description covers the key behaviors and usage. The presence of an output schema offloads return value details, and the description does not need to explain it. It is complete for a 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 coverage is 100%, so baseline is 3. The description adds value by explaining the practical meaning of depth values (orientation vs analysis vs full) and that summary_only applies only at depth=0. This clarifies usage beyond the schema's basic 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 retrieves a token-optimized outline of a file's code units with line numbers. It specifies the verb 'retrieves' and the resource 'outline of file's code units', and the phrase 'token-optimized' distinguishes it from full source retrieval like view_file_source.

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 use the depth parameter for different purposes (orientation, analysis, full detail). While it doesn't explicitly state when not to use this tool compared to siblings like search_code_skeletons, the depth guidance is practical and 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?

Discloses that the tool does not read or modify session.md, describes return format (markdown string), and details error behavior (raises string if role not registered). Since no annotations are provided, the description carries full burden and does so thoroughly.

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 compact but comprehensive: first sentence defines main action, second gives usage guideline, third explains valid role values, fourth describes return and error. Well-structured and front-loaded with key 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?

Given that an output schema exists and parameter coverage is 100%, the description still adds value by explaining return format, error handling, and usage context. It completely addresses the tool's behavior and constraints.

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 already covers both parameters (100% coverage), but description adds critical context: role values come from role_profiles.yaml, provides examples, and notes error handling for unrecognized roles. 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?

The description clearly states the tool assembles and returns a full context bundle for a named agent role, with specific verb 'assembles and returns' and resource 'context bundle'. It explicitly distinguishes from get_session_context by stating when to use each.

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

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

Provides explicit when-to-use (deliberate mid-session role switches) and when-not-to-use (session start, alternative named). Also clarifies that it does not read or modify session.md, giving clear context for safe 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?

With no annotations provided, the description carries the full burden of disclosing behavior. It only states the action without mentioning side effects, permissions, or limitations. The word 'Extracts' implies read-only, but no explicit safety information is given.

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, using a single sentence to convey the purpose. However, the '[ARTIFACT TOOLS]' prefix is slightly redundant, and the brevity sacrifices necessary context.

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 presence of an output schema and full parameter coverage, the description is minimally adequate for a simple tool. However, it lacks usage context and does not explain what 'table of contents' entails or when to use 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%, and both parameters are described in the schema. The description adds no additional meaning beyond the schema fields, 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 clearly states the tool's action ('Extracts table of contents'), specifying the resource type ('table of contents') and distinguishing it from siblings like read_project_artifacts and get_file_skeleton.

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 read_project_artifacts or get_file_skeleton, leaving the agent without context for selection.

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

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

With no annotations, the description must fully disclose behavior. It informs that the tool returns a live directory tree, but lacks details on performance, error handling (e.g., missing project), or whether the output is static or updates. It adequately states the primary action but omits edge-case behaviors.

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

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

The description is two sentences, front-loaded with the main action, and every sentence provides value. There is no unnecessary information, making it 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 an output schema (not shown) and only three parameters with full schema descriptions, the description is largely complete. It could mention that the output is a tree, but that is likely covered by the output schema. Overall, it provides sufficient context 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 input schema has full descriptions for all three parameters, achieving 100% coverage. The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns a 'live directory tree of all files indexed in the code skeleton index' and specifies its use for orientation before scoped searches. This differentiates it from siblings like 'search_code_skeletons' which perform focused searches.

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 this tool to orient before starting a scoped search, providing clear context. It implies when not to use it (e.g., when you need specific file content), but doesn't explicitly state alternatives beyond the hinted scoped search.

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?

Despite no annotations, the description thoroughly discloses behavior: it reads session.md, assembles multiple components, bypasses session.md when start_role is provided, and returns an error for unrecognized roles. No contradictions.

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

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

Two well-organized sentences with a clear section header. Information is front-loaded and every clause adds value. 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 existence of an output schema and the tool's moderate complexity, the description covers all necessary aspects: input modes, output composition, and special behavior for start_role. No 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 coverage is 100%, but the description adds value for start_role by explaining its bypass behavior and error response. The project parameter is briefly described in the schema; the description does not add further constraints.

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

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

The description clearly identifies the tool's function: reading session.md and returning an assembled string of core guidelines, phase-appropriate role guidelines, filtered ADRs, and skill stubs. It distinguishes two modes (with and without start_role), making the purpose specific and actionable.

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

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

The description explains the two usage scenarios (normal and bypass with start_role) and the effect on output. However, it does not explicitly state when to avoid this tool or mention alternative tools (e.g., get_guideline) for simpler needs.

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 the full burden. It implies a read operation but does not disclose whether it is truly read-only, rate limits, or what 'full details' encompasses. Adequate but not rich.

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

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

The description is very concise with one functional sentence. The '[TASK TOOLS]' prefix adds minor context but is not essential.

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

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

For a simple read tool with two required params and no output schema, the description is minimally sufficient but could benefit from clarifying what 'full task details' includes, especially given the many sibling tools.

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 no additional meaning to parameters beyond what the schema already provides.

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 returns full task details, distinguishing it from sibling tools like add_tasks or search_tasks. However, it does not explicitly differentiate from other retrieval tools.

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

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

No guidance is provided on when to use this tool versus alternatives such as search_tasks or list_project_artifacts. The description lacks context for decision-making.

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

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

No annotations provided, so description carries full burden. Discloses creation via template copy, validation, return value, and error conditions. Could mention idempotency or permissions, but still strong.

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?

Well-structured with tag, main action, use case, negative guidance, parameter list, return description, and error note. Every sentence is necessary and informative.

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

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

Given no annotations, description fully covers purpose, usage, parameters, return value, and errors. Agent has sufficient context to decide when and how to invoke.

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?

100% schema coverage gives baseline 3. Description adds value by specifying 'must not already exist' for project and supported template restriction, which are not in 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?

Clearly states it creates a new Marrow project workspace by copying a template, producing a specific artifact tree. Explicitly distinguishes from sibling tools like list_projects and get_session_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?

Provides primary use case (first-run initialization without shell access), alternative for docker-compose, and explicit negative guidance with sibling tool names.

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 fully covers behavior: returns list in reverse chronological order, each entry has backup_name, created_at, size; empty list for no history; raises 404 for nonexistent path. Provides comprehensive disclosure.

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?

Well-organized with clear sections: purpose, usage instruction, return format, error. Every sentence is informative without 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?

Simple tool with 2 parameters, full schema, and output schema. Description covers return format, errors, and usage context, making it complete for agent decision-making.

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 already has 100% coverage with descriptions for both parameters (path and project). Description does not add additional 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?

Clearly states it returns version history for a single artifact file, listing backup snapshots. Differentiates from read_project_artifacts and restore_project_artifact, providing specific verb and resource.

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

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

Explicitly says to use before calling restore_project_artifact and not to use for reading current content, directing to read_project_artifacts instead. Provides context about automatic creation by save_project_artifacts.

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 discloses return structure (list with path and size), error behavior (404), and the effect of the recursive parameter. However, it omits potential rate limits or auth requirements, which are minor for a list operation.

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

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

The description is well-structured: starts with a clear purpose, then explains parameters, followed by usage exclusions, and finally return/error info. Every sentence serves a specific function 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 presence of an output schema, the description adequately covers return structure and error cases. It explains the recursive behavior and path scoping, making the tool's behavior fully predictable.

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 valuable context: examples for path ('docs/features/active', omit for root), and clarifies recursive default and behavior. This goes beyond the schema's brief 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 explicitly states it 'Lists artifact files' with optional subfolder scoping and recursive traversal. It immediately distinguishes from sibling tools like read_project_artifacts and get_project_map.

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 on when not to use this tool: 'Do NOT use to read file content — call read_project_artifacts instead. Do NOT use to browse source code — call get_project_map for the src/ tree.' This clearly guides the agent.

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; description only says 'returns a list'. Does not explicitly state it is read-only or disclose any behavioral traits beyond the obvious.

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 a helpful category tag. Every word is necessary; 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 simple nature and presence of an output schema, the description is sufficient. Does not explain return format, but output schema presumably covers that.

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?

No parameters exist, so baseline is 4. Description adds no parameter info, but schema coverage is 100%.

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 it returns a list of all available projects, using specific verb and resource. It is distinct from sibling tools, though 'available' could be more precise.

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 about prerequisites or scenarios.

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 behavioral traits. However, it only states the basic action without clarifying whether the move is destructive, if it preserves artifact history, or what permissions are required. This is insufficient for safe use.

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 at one line, with no wasted words. The category prefix '[ARTIFACT TOOLS]' provides context. However, it might be too brief, borderline under-specified, but still efficient.

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

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

Given the operation complexity (move/rename), more context is needed: what happens if destination exists, whether it works across folders, and if it logs history. The output schema exists but the description alone does not provide enough for an agent to use it correctly without risk.

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 three parameters have descriptions in the schema (100% coverage), but the tool description adds no additional meaning beyond those basic labels. The baseline for high coverage is 3, and the description does not improve parameter understanding.

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

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

The description clearly states the action: 'Moves or renames an artifact.' It uses a specific verb ('Moves or renames') and resource ('artifact'), and among sibling tools, no other tool performs this exact function, ensuring clear differentiation.

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

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

No guidance is provided on when to use this tool versus alternatives like copying, deleting, or reading artifacts. There is no mention of prerequisites, constraints, or typical scenarios.

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 were provided, so the description carries the full transparency burden — and it delivers. It documents the return contract ('list of result objects — each with path and content'), per-item error semantics ('does not abort the batch'), and precisely what each mode returns (full='entire file', paged='windowed read', section='single section, whole section returned', lines='whole range returned'). This is exemplary behavioral disclosure.

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?

Well-organized with clear visual scannability: bracketed prefix, a mode legend with aligned formatting, bolded field names, and a final usage directive. Every sentence contributes (batch instruction, sibling pointer, return contract, error behavior). Slight deduction because the 'Optional per-item fields' section partially repeats mode information already embedded in the ReadRequest schema, and the bracket format '[ARTIFACT TOOLS]' is a minor style smell.

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 5-mode, 2-level-parameter tool, the description is thorough: it documents return shape, error isolation semantics, batch behavior, and points to the right sibling for the out-of-scope case (src/ files). The explicit 'Returns'/'Raises' statements close the loop. Minor gaps: it doesn't mention pagination behavior for the returned result list or any interaction between 'start_line' and 'paged' mode, though the output schema exists to cover some of this.

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 already 100%, setting the baseline at 3. The description adds value by organizing parameters by read mode and surfacing the mode→required-param dependencies (section requires section_name, lines requires start_line/end_line) more clearly than the raw schema. It also adds the batching semantic (each item in 'reads' is independent). Minor deduction for some redundancy between the mode bullets and the per-item field list.

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

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

The description opens with a specific verb+resource+scope: 'Reads one or more artifact files in a single batch call.' It immediately differentiates from siblings by emphasizing the batch capability, and explicitly distinguishes itself from view_file_source by name. The [ARTIFACT TOOLS] prefix groups it, and the batching purpose is unmistakable.

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

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

Explicit guidance is given throughout: 'Do NOT loop this tool per file — batch all reads into a single call to minimise round-trips' provides a clear behavioral directive, and 'For source code files in src/, use view_file_source instead' names the exact alternative. It also explains when each read mode is appropriate, giving the agent complete when-to-use guidance.

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

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

Discloses that the current live file is overwritten without automatic backup, which is a key behavioral trait. Also specifies return value (confirmation string) and error condition (404 if path/backup_name not found). With no annotations, the description fully informs the agent.

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

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

The description is concise with a header and three sentences. Each sentence serves a purpose: purpose, precondition, return/error. No fluff, 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 complexity (3 required params, destructive action), the description covers prerequisites, behavior, return format, and error handling. With output schema present, the described return is sufficient.

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 value by specifying that backup_name must be an exact string from list_artifact_history and not to guess. This clarifies usage beyond the schema's short 'Backup name' 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 restores a backup snapshot, replacing the live file. It uses specific verb 'Restores' and resource 'backup snapshot of an artifact'. The warning about overwriting without backup and the distinction from sibling tool list_artifact_history enhance clarity.

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

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

Explicitly instructs to use list_artifact_history first to retrieve valid backup_name values. Advises against guessing or constructing backup names. Provides clear when-to-use and when-not-to-use guidance, setting it apart from sibling 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?

No annotations provided, so description fully carries burden. It explains the tool runs steps sequentially, injects variables via template, returns a result object with status/step outputs/elapsed time, and raises specific errors. This is comprehensive for a build execution tool.

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

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

Description is well-structured and front-loaded with the core purpose. It uses bullet-like phrasing for returns and raises. Slightly verbose for the complexity, but still concise enough. The extra details on variables and not-to-use are justified.

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 (build pipeline execution with artifacts), no annotations, and presence of an output schema (described in text), the description covers key aspects: what it does, what it returns, error conditions, and distinguishes from sibling artifact tools. It is complete for an agent to decide and 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?

Input schema covers all parameters with descriptions (100%). Description adds context: variables are for template placeholders like {{FEATURE}}, build_name references manifests in docs/builds/, and that project and build_name are required. While schema already explains basics, description enriches usage semantics.

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 it executes a named build pipeline from a YAML manifest under docs/builds/. It specifies the manifest defines steps and the tool runs them in order. Explicitly distinguishes from reading/writing artifacts by naming sibling tools.

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

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

Explicitly tells when NOT to use it: 'Do NOT use this to read or write individual artifacts — call save_project_artifacts or read_project_artifacts instead.' Also describes return conditions and error cases (404 if name not found, RuntimeError on failure).

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, and it delivers: it discloses atomicity, non-interaction between modes, exact semantics for each write mode, the return shape (list of path/status), and the duplicate-header error with line numbers. It also states the source directory is read-only from the agent's perspective, which is critical behavioral 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 long but every part earns its place: main purpose up front, a tight bulleted mode list, targeted usage warnings, and compact Returns/Raises sections. The structure makes the content skimmable and the mode list easy to parse. No filler or repetition is present.

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

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

For a tool with six modes, nested write requests, and important failure modes, the description is complete: it covers all modes, their constraints, the source-code exclusion, concurrency safety guidance, return values, and a specific error case. The agent has enough information to invoke the tool correctly across the full range of supported operations.

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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: replace_file creates if absent, replace_section raises on duplicate headers, patch requires old_str to be unique, replace_chunk targets line ranges, and delete_section removes a named section. It also clarifies the distinction between content and new_str in patch mode and gives practical preference guidance. This significantly improves an agent's ability to choose and fill 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 opens with a specific verb+resource: 'Creates or updates one or more artifact files in a single atomic batch.' It clearly distinguishes the tool from sibling artifact tools by scoping it to writes and explicitly excluding source code in src/. The six write modes are named and each given a one-line meaning, so an agent can understand the tool's function without ambiguity.

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

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

It gives explicit when-not guidance: 'Do NOT use replace_file when only a section needs updating — use patch or replace_section' and 'Do NOT use this tool for source code in src/.' It also provides mode-selection guidance by describing which mode fits which scenario, such as preferring patch for surgical single-line edits. This goes well beyond a generic 'use for artifacts' statement.

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 data source (code_skeleton_index), result ranking, and scoping, but does not mention permissions, rate limits, or any side effects. As a read-only search tool, this is adequate 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 four sentences, front-loaded with the purpose. It is concise and well-structured, with no redundant information. Could be slightly more compact, but overall effective.

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 100% schema coverage, an output schema exists, and the tool is a search, the description covers the main purpose, return type, and scoping. It is complete enough for an agent to invoke correctly, though it might benefit from mentioning the output schema explicitly.

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 3. The description adds little beyond the schema; it reiterates that root_path scopes to a module and mentions output fields, but does not clarify parameter formats or relationships. Schema already documents parameters fully.

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 performs semantic search over indexed source code skeletons, specifying the resource and action. It distinguishes from siblings like 'semantic_search' and 'search_project_artifacts' by focusing on code skeletons, and mentions returning specific fields (file path, line range, skeleton text).

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 searching code skeletons and mentions scoping with root_path, but does not explicitly state when to use this tool vs alternatives (e.g., 'semantic_search' or 'search_project_artifacts'). No exclusions or when-not-to-use guidance is provided.

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

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

With no annotations, the description carries full burden. It discloses it's full-text, case-insensitive, plain text query. Describes return format and error (404). Missing explicit read-only confirmation but context implies it. Good behavioral coverage.

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?

Well-structured: header with artifact tool context, clear usage instructions with explicit do-not-use cases, and return/error details. Each 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 two required params, output schema present, and no additional complexity, description fully covers usage, constraints, and error scenario. No gaps for agent decision-making.

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 clarifying query is plain text and case-insensitive. Does not reiterate schema but enhances understanding. Justification sufficient.

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 performs full-text search across artifact files in a project, matching content and returning files/sections. It distinguishes itself from sibling tools like semantic_search and search_code_skeletons by specifying scope and use case.

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

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

Explicitly tells when not to use: listing files (use list_project_artifacts) and source code (use search_code_skeletons). Also directs semantic search to semantic_search. Provides clear context for appropriate use.

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 comprehensively describes default behavior (status defaults to 'open'), allowed values for filters, return format (list of summaries with specified fields), and error condition (404 if project not found). Also notes that full content is excluded.

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 well-structured with bullet points for allowed values and clear sections. While slightly long, every sentence is informative and front-loaded with purpose. Could be slightly more concise but effective 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?

Given 4 parameters, output schema exists, and description covers return format, error handling, and usage rules, it is completely adequate for an AI agent to understand and 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?

Schema coverage is 100%, baseline 3. Description adds meaning by listing allowed values for status, priority, and type (though type schema lacks enum), explaining default status and that all parameters except project are optional. This adds value 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 queries the task backlog with optional filters and returns summaries ranked by creation order. It distinguishes itself from get_task_details by explicitly advising against calling that tool on every result.

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

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

Explicitly states when to use: for status checks and task selection, then call get_task_details on the single selected task. Also explains default status behavior and how to retrieve all statuses, providing clear guidance.

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

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

No annotations are provided, so the description carries full burden. It discloses that it calculates embeddings and searches by distance, implying it is computationally heavier than simple search, but does not mention any side effects, permissions, or limits. Adequate but could be more explicit about performance or data 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?

Three sentences, each contributing essential information: the action, the mechanism, and the output. No wasted words, front-loaded with purpose.

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

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 fairly covers what the tool does, how it works, and what it returns. Minor gaps like performance implications but sufficient for selection and invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning to parameters beyond what the schema provides; it only mentions query and return fields. No parameter-specific details like format or constraints.

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 performs semantic search on artifact sections, calculates embeddings, and returns specific fields. This distinguishes it from sibling tools like search_project_artifacts (likely keyword-based) and search_code_skeletons (code-specific).

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. The '[ARTIFACT TOOLS]' prefix provides minimal context, but it does not explain when to prefer semantic search over keyword search or other search 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 discloses the merge strategy, allowed keys, return value, and error case. While some details like authentication or idempotency are missing, the behavioral traits 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?

Well-structured with a header, clear purpose, do's and don'ts, allowed keys list, and return/error info. Front-loaded with the main purpose, no wasted sentences.

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 task structure and sibling tools, the description covers essential usage: what fields can be updated, how the update works, when to use alternative tools, and expected outcomes (return value, error). No 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 descriptions are minimal ('Updates dict'), but the description adds significant meaning: lists allowed keys, their types, and enum values. Also explains merge strategy. This goes well beyond the schema's 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's purpose: partially updates mutable fields on an existing task using a merge strategy. It specifies the verb 'update' and the resource 'task', and distinguishes from siblings like 'complete_tasks' and 'add_tasks'.

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

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

Explicitly states when to use (in-progress changes) and when not to use (close tasks, create tasks), with specific alternative tools named. This provides excellent guidance for the agent.

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 explains the tool reads from the live source repository and requires SOURCE_ROOT configuration, but omits details on error handling, permissions, or behavior when lines are out of range. The read-only nature is implied but not stated.

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 with two sentences: one defining purpose and one stating a prerequisite. Every word adds value; 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 the presence of an output schema (not needing return value explanation), the description adequately covers purpose and prerequisite. However, it could clarify that this tool is for source files only (not artifacts), a nuance hinted but not explicit. Minor gap for a well-defined tool.

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

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

The input schema already provides 100% coverage with descriptions for all 4 parameters. The description reinforces 'precise line range' but adds no new semantic information beyond the schema, meeting the baseline expectation.

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 'Read a precise line range from the live source repository', specifying the verb (read), resource (live source repository), and scope (precise line range). This distinguishes it from sibling tools like get_file_skeleton (structural view) and read_project_artifacts (non-source artifacts).

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 includes a prerequisite ('Requires SOURCE_ROOT to be configured in project/.settings'), providing clear context for when the tool can be used. However, it does not explicitly contrast with alternatives such as get_file_skeleton or search_code_skeletons, missing the opportunity to guide selection.

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