td_connect

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only says 'Wire from_path output -> to_path input' and does not disclose side effects such as whether existing connections are replaced, whether the operation is reversible, or what happens on invalid paths.

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 and front-loaded, using a clear arrow notation to convey the connection direction. It is a single sentence with no wasted words, though its brevity comes at the cost of failing to explain optional parameters.

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 4 parameters, no annotations, and no parameter descriptions in the schema, this description is too sparse. It omits the meaning of from_out and to_in and provides no usage context beyond the core wiring action. While an output schema exists, it does not help clarify input semantics.

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?

With 0% schema description coverage, the description needed to compensate. It clarifies that from_path is an output and to_path is an input, but it leaves the optional parameters from_out and to_in completely unexplained. An agent cannot infer what these integer indices represent.

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 uses the specific verb 'Wire' and specifies the direction 'from_path output -> to_path input.' This distinguishes td_connect from sibling tools like td_set or td_create, which involve different operations.

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 gives no explicit guidance on when to use this tool versus alternatives. It merely states the operation without explaining prerequisites, exclusions, or scenarios where other tools like td_build or td_set would be more appropriate.

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