td_project_text

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

With no annotations, the description carries the full burden and does so well. It discloses that TouchDesigner need not be running, that DAT text is represented as an array of lines (not an escaped string), that joining the array with newline reconstructs the file byte-for-byte, and that oversized networks are refused rather than truncated to preserve parseable JSON.

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 front-loaded with the core purpose and then adds only necessary behavioral and usage details. Every sentence earns its place: purpose, when-to-use, DAT line encoding, and max_bytes/path semantics are all essential and efficiently worded.

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 output schema exists, the description does not need to enumerate return fields. It provides all essential context for successful invocation: what the tool does, when to use it, how DAT text is encoded, how size limits behave, and what path does. No critical operational detail is missing.

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 has 0% description coverage, so the description must compensate. It explicitly explains max_bytes (refusal rather than truncation) and path (narrowing the dump to one component). The file parameter is not explicitly described, but the tool's opening sentence makes its role clear enough as the .toe/.tox file to dump.

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 and resource: 'Dump a whole .toe/.tox network as JSON, without TouchDesigner running.' It further differentiates the tool from td_project_read by explaining that this tool is for cases where the tree is not enough and every parameter, wiring, flags, and DAT code are needed at once.

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 usage guidance is provided: 'Use this when td_project_read's tree is not enough' and concrete examples are given such as before rewriting a component or explaining an unfamiliar project. It also explains when not to rely on the default — a network larger than max_bytes is refused and path narrows the dump — giving the agent clear decision criteria.

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