Skip to main content
An agent is a reasoning system, not a search box. Quality of input directly determines quality of output. The agent works with what you wrote — vague input produces vague output, or worse, wrong output.

​
How a prompt is interpreted

  1. The agent reads your request plus context it already has (specialty, rules, knowledge, available tools).
  2. It forms a plan: the sequence of steps it believes will satisfy your request.
  3. It executes each step via tools (shell, CLI, MCP).
  4. It observes results and adjusts.
  5. It reports what it did, what it found, and whether it succeeded.

​
Anatomy of a good prompt

A strong prompt answers four questions. You do not have to answer all four every time — the more you cover, the better the result.
QuestionExample
WHAT do you want done?”Find the root cause and fix it”
WHERE should it operate?”On prod-web-03 — the checkout service”
HOW should it behave?”@2501:investigate — do not make changes yet”
WHAT does success look like?”Service responds 200 on /health within 5s”

​
Core principles

​
Be specific about the target

VagueBetter
”Check the database.""Check the PostgreSQL database on prod-db-01; connections are spiking and we see timeouts in the API logs.”

​
State the outcome, not just the symptom

VagueBetter
”Something is wrong with the server.""CPU usage on web-03 has been above 90% for 20 min. Find the cause and, if safe, resolve it.”

​
Set boundaries explicitly

There is a meaningful difference between investigate and fix. 
# Investigate-only
@2501:investigate Diagnose why the nightly backup job failed.
Do not make any changes. Report back.

# Remediate
The backup job failed. Identify the cause and fix it so the job can re-run tonight.
When in doubt, start with @2501:investigate. You can always follow up with a remediation task after reviewing.

​
Include relevant context

The agent knows the system it is connected to, but not what happened in your incident channel five minutes ago. Share recent events, deployments, the exact error message — but don’t pad. One clear paragraph beats five vague ones.

​
Do / don’t

Do

  • Name the host, service, or environment in every prompt
  • State investigate-only vs remediate explicitly
  • Include error messages, log snippets, recent context
  • Start narrow — easier to expand scope than undo a broad action

Don't

  • Assume the agent knows what you know
  • Use internal shorthand without explanation (“fix the P1”)
  • Bundle unrelated things in one prompt
  • Write a novel — detailed is good, padded is not

​
Worked examples

​
Incident investigation

Before: "The app is slow, please check."

After: "@2501:investigate The checkout service on prod-web-01 through
prod-web-04 has been responding in over 8 seconds since 09:15 UTC. CPU and
memory look normal in our dashboard. Investigate the root cause. Do not
make any changes — I want to review your findings first."
Names the service, the hosts, the start time, what was ruled out, and the boundary.

​
Routine maintenance

Before: "Clean up the logs."

After: "Rotate and compress logs older than 7 days in /var/log/app/ on
archive-01. Do not delete anything, just compress. Report how much
space was freed."
Specifies the path, the host, the action (compress, not delete), and a confirmation metric.

​
Multi-step remediation

Before: "Deploy the new version."

After: "Deploy version 2.4.1 of the payments service to staging. Steps:
pull the latest image, run migrations, restart the service, verify
/health returns 200. Roll back to 2.4.0 if the health check fails."
Names the version, environment, expected steps, success criterion, and fallback.

​
Investigation with ticket context

Before: "Look at ticket INC0045821."

After: "Ticket INC0045821 reports users in the EU region cannot log in
since 02:00 UTC. The error is 'auth service unavailable.' Investigate
the auth service on eu-auth-01 and eu-auth-02 — logs, service status,
upstream dependencies. Do not make changes. Summarize so I can decide
next steps."
Restates the facts directly so the agent doesn’t have to interpret a ticket ID in isolation.