---
title: 'Tools & project interfaces'
description: 'Stable, deterministic, discoverable interfaces beat clever prompting.'
canonical_url: 'https://darkfactory.dev/factory/tools-interfaces'
markdown_url: 'https://darkfactory.dev/factory/tools-interfaces.md'
collection: factory
date_published: '2026-07-16T00:00:00-04:00'
date_modified: '2026-07-16T00:00:00-04:00'
---

# Tools & project interfaces


**Confidence: high.** *Evidence: controlled study and case study.* *Last substantive change: 2026-07.*

Agents can act only through the tools and project commands they receive. A small interface choice can change model behavior more than a longer prompt.

## The conclusion

**Stable, deterministic, discoverable project interfaces are more valuable than clever prompting.** The harness should make correct actions easy, unsafe actions impossible, and failures attributable. Edit format, tool shape, and middleware materially change outcomes, often more than the wording of a prompt.

## How the thinking got here

Shell and editor loops gave way to rich tool suites, then to standardized repository commands and middleware. A recurring finding is that schema mismatches and tool ergonomics can dominate behavior: an agent handed a clean, discoverable interface outperforms the same agent handed a powerful but confusing one.

## Credible alternatives, and when each is right

| Approach | Right when |
|---|---|
| General shell | flexibility matters more than guardrails |
| Narrow typed tools | safety and predictability matter |
| MCP or API tools | integrating external systems |
| Generated task-specific tools | a repeated task deserves its own verb |
| Computer use | no API exists for the surface |
| Tool-free code emission | the model can express the action directly |

## Where it fails and what we still don't know

Failures include schema-invalid calls, silent tool errors that never reach the agent, and interfaces that make an unsafe action as easy as a safe one. Portability across providers remains fragile. Open questions include tool contracts, capability discovery, semantic versioning, least authority, error-channel design, and cross-model portability.

## What would change our mind

A portable tool-contract standard that holds an agent's behavior stable across providers would remove much of the fragility that currently ties a factory to one vendor's tool shapes.

## Evidence and further reading

- [The Anatomy of an Agent Harness](https://www.langchain.com/blog/the-anatomy-of-an-agent-harness)
- [Deterministic Tool-Schema Compilation](https://arxiv.org/abs/2605.04107)
- [A Methodology for Selecting and Composing Runtime Architecture Patterns for Production LLM Agents](https://arxiv.org/abs/2605.20173)
- [How Claude Code Works in Large Codebases](https://www.claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start)