docs: apply verbatim model experience guidance repo-wide
This commit is contained in:
Tianyi Cui
@@ -38,9 +38,25 @@ The tool never calls a provider's `status()` and never enumerates providers —
|
||||
|
||||
| Context surface | What the model sees | Token effect |
|
||||
|---|---|---|
|
||||
| System prompt | Each config-enabled tool adds one short section: search guidance says to discover current sources and follow with fetch; fetch guidance says to retrieve a specific HTTP(S) URL and cite it. A scoped tool restriction does not remove these independently registered sections. | Fixed guidance cost per request for each config-enabled tool, even when a restriction hides its schema. |
|
||||
| Tool schemas | According to config and scoped restrictions, the model sees `web_search(query)`, `web_fetch(url)`, or both. Result-count and timeout budgets are deployment settings, not model arguments. | Fixed schema cost per request; config disablement removes both schema and guidance, while a scoped restriction removes only the schema. |
|
||||
| Tool-call history and results | Search returns an optional answer and bounded source entries; fetch returns status plus decoded text or markdown-shaped HTML, or a structured error. Queries and URLs remain in call history. | Data-dependent results are resent until compaction. Search sources are capped by `searchMaxResults`; fetch providers cap body size, and timeout policy can replace a late result with a short error. |
|
||||
| System prompt | Search and fetch contribute the exact [web-search](#web-search-guidance) and [web-fetch](#web-fetch-guidance) guidance. A scoped tool restriction does not remove these independently registered sections. | Fixed guidance cost per request for each config-enabled tool, even when a restriction hides its schema. |
|
||||
| Tool schemas | `web_search` has exact description `Search the web for current information. Returns an optional summary answer and a list of source URLs.` and query description `The search query.` `web_fetch` has exact description `Fetch the content of a specific HTTP(S) URL and return it decoded to text.` and URL description `The HTTP(S) URL to fetch.` Result-count and timeout budgets are deployment settings, not model arguments. | Fixed schema cost per request; config disablement removes both schema and guidance, while a scoped restriction removes only the schema. |
|
||||
| Search result | The optional provider-owned answer is followed by `Sources:` and data-dependent lines shaped exactly `- [<title-or-url>](<url>)`, optionally suffixed ` — <snippet> (<publishedAt>)`. With neither answer nor sources the result says `No results found.` A capped list adds `(Showing the first <count> sources. Refine the query for more.)`; every result ends `Cite the relevant URLs above as markdown links in your answer.` | Data-dependent results are resent until compaction and sources are capped by `searchMaxResults`. |
|
||||
| Fetch result | A successful fetch is exactly `Fetched <finalUrl> (HTTP <statusCode>)`, a blank line, and the provider-owned decoded body. Truncation adds a blank line and `(Content truncated. Fetch a more specific URL or section for the full text.)`; failures become `Error: <message>`. Queries and URLs remain in call history. | Provider caps bound body size; retained call arguments and results are resent until compaction, and timeout policy can replace a late result with a short error. |
|
||||
| Argument errors | Blank inputs become exactly `Error: query must be a non-empty string` or `Error: url must be a non-empty string`. | Only the failing call adds these retained tokens. |
|
||||
|
||||
### Verbatim model-visible text
|
||||
|
||||
#### Web search guidance
|
||||
|
||||
```text
|
||||
Use the web_search tool to discover current information on the web. It returns an optional answer plus a list of source URLs. Follow up with web_fetch when you need the full content of a specific result, and cite the relevant URLs as markdown links.
|
||||
```
|
||||
|
||||
#### Web fetch guidance
|
||||
|
||||
```text
|
||||
Use the web_fetch tool to retrieve the content of a specific HTTP(S) URL (for example a result from web_search). It returns the page content decoded to text. Cite the URL as a markdown link when you use its content.
|
||||
```
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ The numeric limits are validated at plugin construction: every cap except `maxRe
|
||||
|
||||
| Context surface | What the model sees | Token effect |
|
||||
|---|---|---|
|
||||
| Web fetch result, indirectly | Through `dsh-tool-web`, the conversation model sees the final URL, HTTP status, and decoded text or markdown-shaped HTML, or a structured retrieval error. Redirects, headers, and transport mechanics are not added to context unless reflected in an error. | Zero direct tokens. `maxBodyChars` bounds decoded result length before the tool records it; the retained result is resent until compaction. |
|
||||
| Web fetch result, indirectly | Through `dsh-tool-web`, the conversation model sees that consumer's exact fetch header plus the data-dependent decoded text or markdown-shaped HTML. This provider's stable failures become `Error: <message>`; messages include `web fetch aborted`, `web fetch timed out`, `web fetch failed: <error>`, `exceeded the maximum of <count> redirects`, `redirect response (HTTP <status>) without a Location header`, `invalid redirect Location "<location>"`, `cross-origin redirect to <origin> is not followed automatically; retry against that URL directly`, `unsupported content type "<type>"`, `response exceeds the maximum of <bytes> bytes`, `URL exceeds the maximum length of <chars>`, `invalid URL: <url>`, `unsupported URL scheme "<scheme>" (only http and https are allowed)`, `credentials in URLs are not allowed`, and `unsupported charset "<charset>"`. Redirects, headers, and transport mechanics are otherwise absent. | Zero direct tokens. `maxBodyChars` bounds decoded result length before the tool records it; the retained result or error is resent until compaction. |
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
|
||||
@@ -39,8 +39,8 @@ DeepSeek returns no provider-generated answer surface this provider trusts as `c
|
||||
|
||||
| Context surface | What the model sees | Token effect |
|
||||
|---|---|---|
|
||||
| Auxiliary DeepSeek search request | A separate DeepSeek model receives the search query and native `web_search` server-tool definition. This request is not part of the conversation model's context. | Separate provider input and output tokens are incurred for each search; `maxTokens` caps generated output and `maxUses` caps native search uses. |
|
||||
| Conversation tool result, indirectly | Through `dsh-tool-web`, the conversation model sees deduplicated URLs, titles, dates, and citation snippets from structured search blocks; provider prose is not trusted as an answer. | Zero direct conversation tokens from registration. Result tokens scale with returned sources and snippets, then the seam enforces the requested source bound. |
|
||||
| Auxiliary DeepSeek search request | A separate DeepSeek model receives exactly `Perform a web search for the query: <query>` as its user text and one native `web_search` server-tool definition. This request is not part of the conversation model's context. | Separate provider input and output tokens are incurred for each search; `maxTokens` caps generated output and `maxUses` caps native search uses. |
|
||||
| Conversation tool result, indirectly | Through `dsh-tool-web`, the conversation model sees deduplicated URLs, titles, dates, and citation snippets from structured search blocks; provider prose is not trusted as an answer. Provider failures become `Error: DeepSeek search aborted`, `Error: DeepSeek search request failed: <error>`, `Error: DeepSeek returned no web_search_tool_result blocks; the request may not have triggered native web search`, or `Error: DeepSeek returned an unprocessable response body: <error>`; HTTP failures pass through their provider message after `Error:`. | Zero direct conversation tokens from registration. Result tokens scale with returned sources and snippets, then the seam enforces the requested source bound. |
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
|
||||
@@ -29,7 +29,7 @@ Exa returns a flat `results[]` and no generated answer, so `content` is omitted.
|
||||
|
||||
| Context surface | What the model sees | Token effect |
|
||||
|---|---|---|
|
||||
| Web search result, indirectly | Through `dsh-tool-web`, the conversation model sees Exa result URLs, titles, first highlight snippets, and publication dates. No generated answer or provider-private response fields enter the tool result. | Zero direct harness-model tokens. Result size scales with the bounded source list and snippets; the seam enforces `maxResults`, and retained results remain until compaction. |
|
||||
| Web search result, indirectly | Through `dsh-tool-web`, the conversation model sees Exa result URLs, titles, first highlight snippets, and publication dates. No generated answer or provider-private response fields enter the tool result. Failures become `Error: Exa search aborted`, `Error: Exa search request failed: <error>`, or `Error: Exa returned an unprocessable response body: <error>`; HTTP failures pass through their provider message after `Error:`. | Zero direct harness-model tokens. Result size scales with the bounded source list and snippets; the seam enforces `maxResults`, and retained results or errors remain until compaction. |
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
|
||||
@@ -29,8 +29,8 @@ This is an **implementation** package: it registers a provider into `ctx.web`, i
|
||||
|
||||
| Context surface | What the model sees | Token effect |
|
||||
|---|---|---|
|
||||
| Auxiliary Perplexity request | A separate Perplexity model receives the search query through its chat-completions endpoint. This request is not part of the conversation model's context. | Separate provider tokens are incurred per search; `maxTokens` caps the generated answer. |
|
||||
| Conversation tool result, indirectly | Through `dsh-tool-web`, the conversation model sees the generated answer plus structured result metadata or URL-only citations. | Zero direct conversation tokens from registration. Answer and source tokens are data-dependent, source count is seam-bounded, and the retained result is resent until compaction. |
|
||||
| Auxiliary Perplexity request | A separate Perplexity model receives `<query>` verbatim as its sole user message through the chat-completions endpoint. This request is not part of the conversation model's context. | Separate provider tokens are incurred per search; `maxTokens` caps the generated answer. |
|
||||
| Conversation tool result, indirectly | Through `dsh-tool-web`, the conversation model sees the generated answer plus structured result metadata or URL-only citations. Failures become `Error: Perplexity search aborted`, `Error: Perplexity search request failed: <error>`, or `Error: Perplexity returned an unprocessable response body: <error>`; HTTP failures pass through their provider message after `Error:`. | Zero direct conversation tokens from registration. Answer and source tokens are data-dependent, source count is seam-bounded, and the retained result or error is resent until compaction. |
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
|
||||
@@ -45,7 +45,9 @@ The failure branches throw `WebError`, whose structured code (plus message detai
|
||||
|
||||
## Model Experience
|
||||
|
||||
Indirectly, through `dsh-tool-web`, which renders normalized search or fetch data and errors as bounded, retained tool results.
|
||||
| Context surface | What the model sees | Token effect |
|
||||
|---|---|---|
|
||||
| Search or fetch result, indirectly | Through `dsh-tool-web`, the model sees bounded normalized provider data. Selection failures become exactly `Error: configured web provider "<id>" is not registered`, `Error: configured web provider "<id>" is registered but unavailable`, `Error: no usable web provider is registered`, or `Error: multiple usable web providers are registered (<ids>); configure one explicitly`; provider failures use the same `Error: <message>` wrapper. | This seam adds no prompt or schema. Only a call result or error adds retained tokens; source caps bound search output. |
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
|
||||
Reference in New Issue
Block a user