Document host guidance when tool results are separately visible to users

Open Beginner friendly
  • Is something wrong?
#985 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
documentation

Research direction

Start with BaseAgent.temporary_system_prompt_addition() and the existing documentation structure; look for the clearest place to add a host-integration example using the shown Python pattern. Done means the docs explain scoped guidance, retaining separate tool and agent outputs, and the limitations around partial, collapsed, or unread cards without introducing a new core API.

Written by the indexing model from the issue text.

Description

Idea: document host-provided context about visible tool output

Some frontends show a tool's own response in an inline card, then show the parent agent's answer separately. The agent may otherwise repeat the whole tool response, or assume the user only sees its final answer.

The goal is both transparency and useful interpretation: retain the tool result and the parent answer, while making their roles clear.

Existing API is sufficient for a first implementation

BaseAgent.temporary_system_prompt_addition() already supports scoped host guidance. Before proposing a new core API, would a small host-integration example be useful in the docs?

Illustrative usage:

ui_context = (
    "This interface can show supported tool responses in separate cards. "
    "When a card is available, add interpretation, caveats or next actions "
    "rather than unnecessarily repeating it. Keep your own answer and provide "
    "requested summaries or quotations. Clearly distinguish disagreement. "
    "Cards may be partial, truncated or collapsed. Do not assume any particular "
    "output was displayed or read, or that the card includes the full result."
)

with agent.temporary_system_prompt_addition(ui_context):
    result = await agent.run_with_mcp(prompt)

The host should establish the scope before constructing/preparing the run's model instructions, and retain it through tool continuation. This describes an interface capability, not proof that a particular viewer received/read a particular result.

Why not put UI state into core yet?
  • Headless/terminal hosts may not have cards at all.
  • An event emitter does not prove browser delivery.
  • Provider-supplied text should not become trusted display-status metadata.
  • Preview completeness and collapsed details make "the user already saw it" too strong.
  • The existing extension API avoids new core flags, result fields and replay behavior.

We have exercised this pattern with deterministic continuation tests and a real tool-backed conversation in a separate frontend. Guidance reached the model and both outputs survived reopening. The model still repeated some of a small result, so this is not a claim of reliable deduplication or improved answer quality from one run.

Would you prefer a documentation example around the existing API, or have other hosts demonstrated a need for a more structured presentation-context contract? This is a design/documentation proposal, not a request to add a new core abstraction immediately.

Dominant language
Python
Stars
875
Forks
294
Avg merge
1d 16h
Merged PRs (30d)
73

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from mpfaffenberger/code_puppy

All issues in mpfaffenberger/code_puppy

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.