Read a single scene's prose, outline plan, and the characters and places appearing in it, using project and node IDs from search or outline results.
Read one scene: its prose, its outline plan, and which characters and places appear in it. One node at a time — to find a scene, use search_project or get_outline.
| Name | Required | Description | Default |
|---|---|---|---|
| nodeId | Yes | From get_outline or a search result. | |
| projectId | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, and the description adds useful behavioral context: it is scoped to a single node and returns specific content types. It does not mention errors or permissions, but the annotation plus the explicit single-node constraint covers the essential behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences: the core action and content are front-loaded, followed by the single-node limitation and routing advice. There is no filler or redundant restating of the tool name.
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 what is returned, how to obtain the scene identifier, and the single-node constraint. With readOnlyHint declaring safety and no output schema, this is close to complete for a simple read tool; the main residual gap is the meaning of projectId.
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 50%, with only nodeId having a description. The description adds context by indicating nodeId comes from get_outline or a search result, which helps an agent populate it correctly. However, projectId remains undocumented in both the schema and description, so it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Read one scene') and enumerates the returned contents: prose, outline plan, and characters/places. It also distinguishes itself from discovery tools like search_project and get_outline, making its 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?
It explicitly tells the agent how to find a scene ('use search_project or get_outline') and sets a clear expectation that the tool reads only one node at a time. It does not list explicit when-not-to-use cases, but the stated scope and routing are sufficient for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.