Agenetix

Agent SDK

Tool selection in embedded agents

Learn how Emcy narrows MCP tools and client tools before each turn, and how agent boundaries, metadata, prompts, and context shape the final choice.

10 sections

Emcy does not ask the model to scan your full tool catalog on every turn.

Instead, embedded tool use is guided by a few layers that work together:

  1. the agent decides which MCP servers and enabled tools are even eligible
  2. Emcy narrows that set with semantic preselection
  3. the model reasons over the smaller shortlist plus any clientTools you exposed

That separation is the value add.

It keeps prompt size bounded, makes tool choice more reliable as catalogs grow, and gives you real tuning levers instead of hoping a bigger prompt will stay stable.

What actually guides selection#

Tool selection quality comes from the full configuration surface, not one magic prompt.

1. Agent boundaries#

The agent is the first filter.

If a server is not attached to the agent, or a tool is disabled, it cannot be selected.

This is the cleanest way to reduce noise.

2. Tool metadata#

For MCP tools generated from OpenAPI, the best signals are:

  • operationId
  • summary and description
  • HTTP method
  • path segments
  • parameter names

Those fields give Emcy better semantic signal before the main model turn.

If two tools look nearly identical, selection gets worse no matter how good the model is.

3. Semantic preselection#

Before the main LLM call, Emcy narrows the agent catalog to a smaller relevant set.

That means the model is not mixing retrieval and reasoning in the same step.

Instead of scanning hundreds of tools, it sees a shortlist that already matches the user's intent.

This improves:

  • latency
  • prompt size
  • consistency
  • observability

4. Agent prompt#

The agent System Prompt does not replace tool metadata, but it does guide behavior.

Use it for policy and sequencing rules such as:

  • when the agent should ask before destructive actions
  • which workflows require confirmation
  • which client tool should run after a server mutation
  • how the final answer should summarize what happened

Good prompt example:

TEXT
If you create, delete, or update a todo through MCP, call refreshTodoData before you answer so the host page reflects the latest state.

That kind of instruction helps the agent choose the right next step after it has already found the right tools.

5. Per-turn host context#

The Agent SDK appContext field is useful when the host app wants to add lightweight runtime guidance.

Example:

TSX
useAppAgent({
  appContext={{
    hostRefreshInstruction:
      "After any server-side invoice mutation, call refreshInvoices before you answer so the host page reflects the latest data.",
  }}
});

Use appContext for dynamic hints tied to the current screen or workflow.

Use the agent prompt for steady rules that should apply to every conversation.

6. Client tools#

clientTools are also part of the available action set.

They are not discovered from OpenAPI. You define them explicitly in the host app, so their names, descriptions, and parameter shapes matter just as much.

Examples:

  • refreshTodoData
  • fillQuickAddForm
  • navigateToInvoice
  • selectCustomerTab

If a tool name is vague, the model has less chance of using it correctly.

7. Built-in interaction actions#

The App Agent layer also provides built-in interaction actions:

  • requestApproval
  • requestInput

These are part of the agent's available local action set.

That means your prompt and app context can teach the agent when to:

  • ask for approval before destructive or multi-step work
  • ask for structured missing inputs before continuing

Those choices are part of tool selection too.

Why this is better than dumping the full catalog into the prompt#

The prompt-all-tools approach looks simple at first, but it scales badly.

As more endpoints and more MCP servers get added, every request pays for that growth even when most tools are irrelevant.

Emcy's approach keeps the model focused on the user's task instead of on first-pass search over a warehouse of tools.

That is why the improvement happens before the main reasoning step.

Practical tuning advice#

If you want better tool selection, start here:

  • keep each agent tight around one product surface or job to be done
  • write clear operationId values and endpoint summaries
  • disable tools that should not be callable yet
  • keep clientTools small and specific
  • use the agent prompt for ordering and safety rules
  • use appContext for runtime hints that depend on the current page
  • use requestApproval and requestInput intentionally instead of free-form conversational detours for every interruption

For the deeper architecture behind semantic preselection, see The Best Tool-Selection Improvement Happens Before the LLM and Token-Efficient Tool Selection: How We Scaled From 10 Tools to 300.