Building API endpoints with Claude: Practical prompt engineering lessons from a 70+ endpoint project

Practical prompt engineering for action-taking agents

A developer building a LinkedIn automation API with 70+ endpoints, server-side execution, and Chrome extension authentication used Claude to write approximately 80% of the code. The project revealed specific lessons about structuring prompts for agents that perform actions like API calls, data extraction, and decision trees versus agents that only chat.

The contract approach to prompts

The developer found that natural language instructions like "find relevant leads on LinkedIn and send them a personalized connection request" led to problems: Claude would hallucinate fields, skip validation, and chain unnecessary API calls. What worked was treating every agent prompt like a function signature with explicit constraints:

• INPUTS: Exactly what the agent receives (schema, types, edge cases)
• BOUNDARIES: What the agent must NOT do (no fallback guesses, no skipped fields, no invented data)
• OUTPUT CONTRACT: Exact shape of what comes back, including error states
• DECISION RULES: If X then Y, if Z then stop — no ambiguity

Specific lessons learned

"Be creative" is problematic for action agents: Every time room for interpretation was left in action-taking prompts, Claude would produce unexpected results. For agents that execute real actions, zero creativity is preferable, saving creativity for content generation tasks.

Error handling is essential: Approximately 40% of prompt tokens were dedicated to "what to do when things go wrong." Without this, Claude would either retry infinitely or silently swallow errors and return partial data as if everything was fine.

Chain-of-thought trade-offs: Forcing every agent to output a reasoning step before acting costs about 15% more tokens but saves debugging hours. When something breaks, the developer can read exactly why the agent decided to do what it did.

Pattern matching over persona prompts: Instead of using prompts like "you are a senior engineer," the developer pastes a real example of good output and says "match this pattern exactly." Claude performs better at pattern matching than role playing.

Model selection strategy: Simple extraction and formatting tasks are routed to Sonnet (or even Haiku), while only complex decision-making uses Opus. This approach reduced API costs from painful to manageable, as most agent tasks don't require Opus.