read_project_artifacts

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.