NeuroAPIPrompt engineering
How to write prompts that get useful, structured, predictable answers from /agent/ask.
This page is about prompt craft - wording, structure, constraints. For protocol patterns (streaming, retries, multi-turn), see Examples.
Be specific about output shape
The fastest improvement in answer quality is telling the model what "good" looks like. Specify length, format, and tone up front.
Bad: "Tell me about TSMC."
Good: "Give me a 3-bullet brief on TSMC's competitive moat - one
sentence each, written for a public-equities analyst."Length, format, and audience are three independent dials. Set them all when it matters.
Prefer constraints over hopes
"Reply as JSON" is a hope. "Reply with a JSON object with keys
title (string), summary (string ≤ 200 chars), tags (array of
≤ 5 strings)" is a constraint.
curl -s https://api.neurobro.ai/api/v1/agent/ask \
-H "Content-Type: application/json" \
-H "X-API-Key: $NEUROAPI_KEY" \
-d '{
"prompt": "Read the earnings transcript excerpt below and respond with a JSON object with keys: ticker (string), sentiment (one of \"bullish\" | \"neutral\" | \"bearish\"), drivers (array of <=5 short strings). Output the JSON and nothing else.\n\nTRANSCRIPT:\n<paste here>"
}'Always validate the parsed result on your side. Treat any field-level constraint as a strong suggestion, not a guarantee - your code is where invariants get enforced.
Use message_history for context, not the prompt
When you need the model to remember earlier turns, send them in
message_history, not concatenated into prompt. Two reasons:
- It scans cleanly. The role boundaries are explicit; the model can tell what is the new question versus prior context.
- It composes. Your code can trim the oldest turns when the
transcript grows; rewriting a long blob
promptis harder.
The API is stateless, so on every call you re-send the entire history you want considered. See recipe 2 in Examples.
Pick a mode deliberately
| Mode | What it's for |
|---|---|
fast | Quick responses with standard reasoning and core market knowledge. Good for asset checks, narrative pulses, and high-volume financial Q&A. |
smart (default) | Stronger reasoning over complex financial questions, with deeper market context. Good for technical analysis, trade setups, and fundamental stock research. |
max | Neurobro's most capable tier: deep multi-asset investigations, fundamental analysis with broad market coverage, and the highest-stakes research. |
When in doubt, leave it at smart (the server default) and instrument
usage.cost_units per call so you can see what you're spending.
Plan-level economics live in Pricing.
Streaming changes how you prompt
When stream: true, the user sees the prefix first. Optimize for
top-down readability:
- Don't ask for "a summary at the end" - the user reads the beginning before the end exists.
- Do ask for the conclusion up front, details after. "Start with the answer in one sentence, then expand."
- Do structure long answers as numbered sections so the user can parse them as they arrive.
Common pitfalls
What not to put in prompts
- API keys or any secret you wouldn't paste in a third-party form.
- Customer PII you don't have a basis to share with model providers.
- Long blobs of unstructured input you haven't validated for size - set a budget on your side and truncate before sending.
If you have a compliance constraint that needs a specific data
boundary, see Security & data and contact
[email protected].