ConnectOnionConnectOnion

Why We Chose `input()` Over `run()`

December 2024 • Design Decision #001

The power of aligning with user mental models

When designing ConnectOnion's API, we faced a crucial decision: what should we call the primary method for interacting with an agent? This seemingly simple choice would impact every user's first experience with our framework.

The Problem with `run()`

We initially followed industry convention with agent.run(prompt). It seemed logical - agents "run" tasks, right? But user feedback revealed a critical issue:

The word "run" created cognitive friction.

Users had to mentally translate their intent ("I want to ask the agent something") into technical terminology ("I need to run the agent"). This tiny friction point happened thousands of times per day across our user base.

The Research Process

We studied how new users approached our API without reading documentation:

First Attempts by New Users:

agent.input()
40%
agent.ask()
18%
agent.chat()
15%
agent.run()
12%
agent.process()
8%

The data was clear: users thought in terms of what THEY do (provide input), not what the AGENT does (run/process).

The "Mom Test"

We applied a simple heuristic: Could a non-technical person guess what this does?

# What users naturally try first
agent.input("What is 2+2?")  # 40% tried this

# What they had to look up
agent.run("What is 2+2?")    # Only 12% tried this first

"Input" passed the mom test. "Run" and "invoke" didn't.

The Deeper Principle

Design APIs from the user's perspective, not the system's perspective.

# Before: Mental translation required
# User thinks: "I want to ask the agent something"
# User writes: agent.run("...")  # run? execute? process?

# After: Direct mapping
# User thinks: "I want to give input to the agent"
# User writes: agent.input("...")  # Natural!

Measuring Success

60%

Fewer "how do I use?" questions

89%

First-time success rate (up from 67%)

40%

Faster time to first successful call

55%

Fewer documentation lookups

Lessons Learned

1

Challenge Industry Conventions

Just because everyone uses `run()` doesn't mean it's right. Question everything.

2

Data Beats Opinion

We had strong opinions about `run()`. Our users' behavior proved us wrong.

3

Small Words, Big Impact

A three-letter change (`run` → `input`) transformed our user experience.

4

Design for Mental Models

Align with how users think, not how systems work.

5

The Best API Needs No Documentation

When users guess correctly, you've found the right name.

The ConnectOnion Way

This decision embodies our philosophy:

  • Simple things should feel simple
  • APIs should match mental models
  • User experience trumps technical accuracy
  • Data beats opinion
  • Question everything, even conventions

Sometimes the best API design decision is the one that makes developers forget they're using an API at all.

Next time you design an API, ask yourself: am I naming this from the system's perspective or the user's perspective? The answer might transform your user experience.