Prompting Best Practices#

This guide helps developers write effective prompts for the Silicon Labs Simplicity AI SDK when developing, debugging, porting, and testing applications. It is intended for engineers who use an AI model as part of their development workflow, whether the model is generating code, analyzing an existing project, using connected tools, or producing an implementation plan.

The goal is not to prescribe one universal prompt. Different tasks need different levels of context, constraints, tools, and verification. Instead, this guide provides a practical framework that developers can adapt while keeping prompts clear, focused, and testable.

The guide also covers two decisions that directly affect results: selecting a suitable model and exposing the right Model Context Protocol (MCP) servers. A well-written prompt cannot compensate for a model that is poorly matched to the task or for missing access to required project information. Conversely, enabling unnecessary tools can increase complexity, expose irrelevant context, and make tool selection less reliable.

What Makes a Prompt Effective#

An effective prompt clearly communicates the developer's intent to the model. At a minimum, the model should understand:

• The objective: what the developer wants to accomplish.

• The context: information the model needs to understand the task.

• The constraints: conditions and boundaries the model must follow.

• The expected output: what the model should produce.

• The success criteria: how the result will be evaluated.

Prompts should describe the desired outcome and the important boundaries without prescribing every reasoning step. Detailed process instructions are useful when a workflow has mandatory stages, but unnecessary procedural detail can distract the model from the actual goal. Include an instruction, example, or tool only when it changes the expected behavior or prevents a known failure.

Good prompts also distinguish between investigation and implementation. For example, a request to diagnose a defect does not necessarily authorize code changes, while a request to fix the defect normally implies making the relevant changes and validating them. Stating the intended scope prevents both incomplete work and unintended modifications.

Finally, prompts should be treated as testable development artifacts. Their quality should be judged using representative tasks and observable results, not by how detailed or polished they appear. Start with the smallest prompt that communicates the task reliably, evaluate the output, and add targeted guidance only when a specific weakness is identified.

Recommended Prompt Structure#

Objective#

State the task in one or two sentences. The objective should describe the outcome, not the method. For example, "add a GATT characteristic that controls the onboard LED" is clearer than "use the GATT configurator and modify the project." If the request is investigative, state it explicitly. For example, "determine why the LED stays on after BLE disconnect" rather than "fix the LED bug."

Context and Inputs#

Provide the information the model cannot reliably infer. This typically includes the project or example name, target board or connected hardware, SDK version, and any relevant files or behaviors already observed. Reference local project state when it matters: open files, build errors, serial log output, or debugger observations.

When the task depends on SDK knowledge, the model can retrieve documentation, examples, components, and compatibility data through the knowledge-base tools. You do not need to paste large SDK excerpts into the prompt unless they are project-specific. Do specify filters that narrow the search, such as technology (for example, bluetooth), board name (for example, brd2602a), or example name (for example, bluetooth_soc_thermometer).

Requirements and Constraints#

List conditions the model must follow. Common constraints for AI SDK workflows include:

• Scope: specify whether the model should only investigate, propose a plan, or also edit, build, flash, and validate.

• Hardware boundaries: name the board or kit to target; ask the model to verify connected hardware before flashing when multiple boards may be attached.

• Preservation: identify files, APIs, or behaviors that must not change.

• Tool use: direct the model to use specific capabilities when absolutely sure. For example, serial monitor for log capture, GDB for breakpoints, or GATT configuration tools for service changes.

Constraints should prevent known failure modes without dictating every implementation step.

Expected Output#

Describe what the model should deliver. Depending on scope, this may include code changes, project configuration updates, a build result, flash confirmation, validation steps, or a written analysis. Be explicit about artifacts you want to review before accepting the work, such as diffs, log excerpts, debugger observations, or a short summary of assumptions made.

For end-to-end tasks, state the full workflow you expect: modify the project, regenerate metadata if components changed, build, flash to the connected board, and validate behavior on hardware.

Success Criteria#

Define how you will decide whether the result is acceptable. Success criteria should be observable and testable. Examples include: the project builds without errors; the LED toggles on GATT write; advertising interval is 100 ms; serial logs show connect and disconnect events; the device is discoverable in a mobile app.

Avoid vague criteria such as "make it work" or "follow best practices." Tie criteria to the stage of development you are working on: configuration, build, flash, debug, or fix.

Reusable Prompt Template#

Adapt this template for most AI SDK tasks:

Objective: [What you want accomplished in one or two sentences.]

Context:

• Project/example: [name or path]

• Board/hardware: [board ID or "use connected board"]

• Observed behavior: [errors, logs, or symptoms, if any]

Requirements and constraints:

• [Scope: investigate only / implement / build / flash / validate]

• [Language, toolchain, files not to change, etc.]

Expected output:

• [Code changes, build, flash, logs, analysis, etc.]

Success criteria:

• [Observable outcomes that prove the task is done]

Good and Bad Prompt Examples#

Developing Applications#

Bad Prompt#

Create a BLE project with an LED.

Improved Prompt#

Create a simple Bluetooth LE SoC project for my connected radio board. Add a writable GATT characteristic that turns the onboard LED on when a write command is received. Use an existing empty or thermometer example as the starting point if compatible. Build with GCC, flash to the connected board, and validate that the LED responds to a GATT write from a phone app.

Why the Improved Prompt Works Better#

The improved prompt names the technology, hardware target, and desired behavior. It gives the model permission to select a suitable starting example, specifies the end-to-end workflow, and defines validation on real hardware. The bad prompt leaves board selection, GATT design, build steps, and success criteria unspecified.

Debugging Applications#

Bad Prompt#

The LED is broken. Fix it.

Improved Prompt#

In my bluetooth_soc_empty project on BRD2602A, the onboard LED turns on when a BLE central connects but does not turn off on disconnect. Investigate the connection event handling, add logging at the critical points, rebuild and reflash, then capture serial monitor output for 30 seconds while I connect and disconnect. Use the logs to identify the cause and apply a fix. Do not change unrelated GATT services.

Why the Improved Prompt Works Better#

The improved prompt describes observed behavior, names the project and board, scopes investigation to connection handling, and directs the model to use logging and serial monitor feedback before fixing. It also limits scope to avoid unrelated edits. The bad prompt provides no reproducible symptom, no project context, and no validation method.

Porting Applications#

Bad Prompt#

Port this project to my custom board.

Improved Prompt#

Retarget my bluetooth_soc_thermometer project from BRD4187C to my custom PCB with EFR32BG24. Preserve BLE GATT behavior and application logic. Update pin mappings, clock configuration, and board-specific components only as needed. Verify board and project compatibility, regenerate the project after component changes, build with GCC, and list any manual hardware assumptions you made.

Why the Improved Prompt Works Better#

The improved prompt identifies source and target hardware, states what must be preserved, and calls out the configuration steps porting normally requires. It asks for explicit assumptions rather than silently guessing pin assignments. The bad prompt does not name the source example, target part, or constraints, which often leads to incomplete or incorrect board retargeting.

Testing Applications#

Bad Prompt#

Test whether this works.

Improved Prompt#

Validate my modified bluetooth_soc_thermometer project on the connected board. Build and flash the project, start the serial monitor, and confirm that temperature advertisements or GATT notifications occur at the expected interval. If behavior is unclear, add temporary logging, rebuild, reflash, and capture logs during a 30-second observation window. Report pass/fail against these criteria: clean build, successful flash, and observable temperature updates.

Why the Improved Prompt Works Better#

The improved prompt defines the validation workflow, names the example, specifies tooling for observation, and lists concrete pass/fail criteria. It allows iterative logging when initial evidence is insufficient. The bad prompt does not say what "works" means or how success will be observed.

Model Selection and Evaluation#

Model selection should be based on the application's requirements rather than the assumption that the most capable model is always the best choice. A model is suitable when it delivers the required quality within acceptable limits for response time and operating cost.

Selection Criteria#

Task Complexity#

Consider how much reasoning the task requires and how much uncertainty the model must handle. Straightforward generation and classification tasks may perform well with a smaller model. Complex debugging, application porting, or tasks involving several dependent decisions may require a more capable model.

Start with a model that is likely to handle the task, then use evaluation results to determine whether additional capability is necessary. Increasing model size or reasoning effort should address a measured weakness rather than serve as the default response to poor results.

Accuracy, Speed, and Cost#

Model selection involves balancing output quality against response time and cost. Quality-sensitive workflows may justify a more capable model, while interactive or high-volume workflows may place greater importance on speed and efficiency.

Establish the minimum acceptable quality before comparing models. The preferred model is the least resource-intensive option that consistently meets that standard. This prevents cost or speed improvements from being accepted at the expense of application reliability.

Context and Tool Requirements#

Confirm that the model supports the capabilities required by the application. These may include the necessary input types, sufficient context capacity, structured output, or reliable tool use.

A large context window should not replace careful context selection. Supplying only relevant information generally makes behavior easier to evaluate and reduces unnecessary processing. Likewise, MCP servers and other tools should be enabled only when they contribute directly to the task.

Evaluating Models on Representative Tasks#

Evaluate models using tasks that reflect real development work, not isolated trivia questions. Representative tasks for the AI SDK include: selecting and extending an example project, adding a component or GATT characteristic, resolving a build error, flashing to a connected board, and validating behavior with logs or a debugger.

For each candidate model, run the same prompt on the same project and compare outcomes against your success criteria. Record whether the model chose a compatible example, produced a clean build, used tools appropriately, and reached a verifiable result on hardware. Note response time and how many follow-up prompts were required.

If a model fails consistently on one stage, such as project selection, code generation, tool use, or validation, switch models for that class of task rather than compensating with longer prompts. When results are close, prefer the model that needs fewer corrections and produces more testable intermediate outputs.

Recommended Models#

The AI SDK does not provide the language model; results depend heavily on the model you select. GPT Sol-5.6 and Claude Opus 5 class models perform best on tasks that combine reasoning, code edits, and tool orchestration.

Use the following guidance as a starting point:

• Complex workflows (new project creation, multi-file changes, build/flash/validate loops, debugging with GDB or serial monitor): prefer a highly capable model such as Claude Opus 5 or an equivalent top-tier option available in your environment.

• Focused edits (single API change, parameter update, small feature addition to an existing example): a mid-tier model such as Claude Sonnet 5 or equivalent models may be sufficient if evaluation shows consistent quality.

• Documentation-style questions (API usage, protocol behavior, board pin definitions): smaller models may be adequate when tool access to the knowledge base is enabled.

Re-evaluate model choice when you change task type, SDK version, or enabled MCP servers. A model that works well for Q&A may still struggle with hardware validation unless the prompt and tools are explicit.

MCP Server Selection#

The AI SDK exposes task-specific capabilities through MCP servers. Enabling the right servers improves accuracy; enabling too many increases context use and can make tool selection less reliable.

Use only the Silicon Labs AI SDK MCP servers required for the current task. The minimal set is:

When to Enable an MCP Server#

Enable a server only when the task depends on it:

• Knowledge base - Ideation, API or docs questions, example discovery, component search, and compatibility checks.

• AI SDK helpers - First-time project setup, refreshing AGENTS.md, or questions about the resolved SLC project inventory.

• Tool locator - Creating, modifying, regenerating, or upgrading projects through SLC and other SLT-managed CLIs.

• Build tool - Compile and build-error resolution.

• GDB - On-target flash, breakpoints, stepping, stack traces, and variable inspection.

As a rule, enable the minimum set for the current stage: discover, create or configure, build, flash, or debug.

When to Disable an MCP Server#

Disable servers that are not required for the current prompt. Unused servers consume context and add tool choices the model may invoke incorrectly. For example:

• Disable silabs-gdb-mcp for documentation-only or project-search tasks.

• Disable silabs-build-tool when you are only searching docs or selecting an example.

• Disable silabs-tool-locator for pure Q&A that needs only the knowledge base.

• Keep third-party MCP servers disabled unless the task explicitly requires them.

If a workflow is going in the wrong direction, simplify the enabled toolset and break the task into smaller prompts rather than enabling every available server at once.

Handling Missing or Failing Servers#

If a required server is unavailable, state the limitation in the prompt and adjust scope. For example, without silabs-gdb-mcp, ask for build-only validation and list manual flash or debug steps you will run locally. Without silabs-knowledge-base, provide more project context in the prompt and expect weaker example selection.

When a server fails mid-task, capture the error, retry once if appropriate, and continue with an alternate path if possible, such as manual build commands, local flash, or a narrower sub-task. Do not assume a failed tool call means the underlying task is impossible; it may indicate authentication, environment, or server configuration issues.

Ask the agent what it can do with currently available tools if you are unsure whether a workflow is supported.

Project Instructions with AGENTS.md#

What Belongs in AGENTS.md#

AGENTS.md provides persistent instructions the agent reads across sessions. It should contain project-specific facts and conventions that are stable and repeatedly useful:

• Target board, part, SDK version, and primary technology (for example, Bluetooth LE on SiSDK 2026.6.x).

• Preferred toolchain and build commands.

• Project layout conventions and where generated files live.

• Validation commands or hardware checks used before accepting changes.

• Scope boundaries, such as which directories are hand-edited versus generated.

Do not duplicate entire SDK manuals or long API references in AGENTS.md. The knowledge-base tools already provide documentation search; AGENTS.md should capture what is unique to your repository and workflow.

Repository Conventions and Validation Commands#

Document commands the agent should run to verify its work, such as SLC regenerate after component changes, GCC build targets, and flash or serial-monitor steps for smoke tests. Include board-specific notes, such as LED and button pin definitions, required radio board, or external wiring assumptions.

If you use specific branch naming, commit message format, or forbidden directories, state those briefly.

Keeping Instructions Focused and Current#

Review AGENTS.md when the SDK version, target hardware, or build system changes. Remove stale commands and examples that no longer apply. Prefer short, testable statements over broad coding philosophy.

When instructions grow long, split stable hardware and toolchain facts from task-specific notes. Long documents dilute attention; the agent should not need to parse obsolete guidance to complete a routine build or flash.

Common Failure Modes and Iteration#

Common Prompting Problems#

• Underspecified objective: "make a BLE app" without behavior, board, or validation steps.

• Missing scope: investigation prompts that implicitly trigger large refactors, or implementation prompts that stop at advice only.

• Wrong tool exposure: hardware or debugger tools disabled when validation is required, or every server enabled for a simple docs question.

• No success criteria: the model cannot know when to stop or what to verify.

• Buried context: critical errors or log lines omitted, forcing guesswork.

• Over-prescribed process: long step lists that distract from the actual outcome when a shorter goal statement would suffice.

Diagnosing Weak Results#

When output quality is poor, identify which stage failed: example selection, project configuration, code correctness, build, flash, or validation. Check whether the model used available tools, such as compatibility search before project creation, regenerate after component changes, serial monitor, or GDB for evidence.

Compare the model's assumptions to your project state. Wrong board, wrong example, or stale generated files are frequent causes of plausible but incorrect solutions. Ask the model to list assumptions and evidence before making further changes.

Improving One Element at a Time#

Change one variable per iteration: clarify the objective, add board context, enable a missing MCP server, switch model tier, or tighten success criteria. Avoid rewriting the entire prompt and all tooling at once; that makes it hard to tell which change helped.

For multi-step workflows, decompose failing workflows into stages. For example, create the project first, then build, then flash, then validate; this is the approach recommended when an end-to-end prompt goes off track.

Re-testing After Changes#

After each prompt or tooling adjustment, re-run the same representative task and compare against your success criteria. Confirm that the builds are clean, generated artifacts are consistent, and hardware behavior matches expectations.

A successful build is necessary but not sufficient. Re-test observable behavior on the board when the task involves BLE, GATT, advertising, or peripherals. Keep brief notes on model, enabled servers, and outcome to build a reliable workflow over time.

Developer Checklist#

Before Running the Prompt#

• Objective states the desired outcome in one or two sentences.

• Context includes project/example name, board or hardware, and SDK/technology where relevant.

• Scope is explicit: investigate, implement, build, flash, and/or validate.

• Success criteria are observable and testable.

• MCP servers match the task; unnecessary servers are disabled.

• Model tier is appropriate for task complexity.

• AGENTS.md reflects current board, toolchain, and validation commands if the agent relies on it.

Before Accepting the Output#

• Changes match the requested scope; unrelated files were not modified without reason.

• Project regenerates and builds cleanly with the expected toolchain.

• Board and compatibility assumptions are documented and correct.

• Flash and runtime validation were performed (when necessary).

• Logs, debugger output, or app observations support the stated success criteria.

• Remaining risks or manual follow-ups are called out explicitly by the agent.

Related Topics#

• User Guide

• Quick Reference

• AI-Assisted Project

• Work with Existing Projects