Read a persistent investigation to retrieve its artifact identities, evidence references, and analyst findings, with returned artifact paths resolving in the current workspace.
Read one persistent investigation, its artifact identities, evidence references and analyst findings. Returned artifact paths resolve in the current workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
Changes observed during successful MCP inspections.
v0.4.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing what is returned and the caveat that 'returned artifact paths resolve in the current workspace' — a non-obvious resolution rule. It stops short of covering failure modes (missing project) or result size.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the core action front-loaded and the path-resolution caveat placed second where it reads as a qualifier. Nothing is wasted, though the second sentence could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does carry some of the return-value burden by naming the three result categories, and the workspace-resolution note is a genuine completeness win. However, for a read tool returning a nested investigation record, it omits structure, ordering, and what happens when the id is unknown.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%: the single parameter carries only a regex pattern and length bounds, with no prose explaining that project_id is the identifier produced by create_project. The description never mentions the parameter, so an agent gets no help on where the id originates or whether it accepts other formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Read') and a specific resource ('one persistent investigation'), then enumerates what comes back: artifact identities, evidence references, analyst findings. This clearly separates it from write-side siblings like create_project and import_artifact, though it never names a sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call this versus create_project, list_evidence, or read_evidence; the only hint is the word 'one', implying single-project lookup by id. No prerequisites, no exclusions, no alternative routing are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.