From 356e1f82f22789ac40350ed7e995cd8fc2832409 Mon Sep 17 00:00:00 2001 From: Steven H Date: Wed, 30 Sep 2026 10:06:20 +0100 Subject: [PATCH 1/5] Improve the prompt for the Ask endpoint --- packages/gitbook/src/routes/markdownPage.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/gitbook/src/routes/markdownPage.ts b/packages/gitbook/src/routes/markdownPage.ts index c5460f4a36..228fd12bc9 100644 --- a/packages/gitbook/src/routes/markdownPage.ts +++ b/packages/gitbook/src/routes/markdownPage.ts @@ -85,7 +85,7 @@ If the exact page cannot be found, you can still retrieve the information using ### Option 1 — Ask a question (recommended) -Perform an HTTP GET request on the documentation index with the \`ask\` parameter, and the optional \`goal\` parameter: +Perform an HTTP GET request on the documentation index with the \`ask\` and \`goal\` parameters: \`\`\` GET ${context.linker.toAbsoluteURL( @@ -96,7 +96,7 @@ GET ${context.linker.toAbsoluteURL( \`\`\` \`ask\` is the immediate question: it should be specific, self-contained, and written in natural language. -\`goal\` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. +\`goal\` is the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal, so answers with a goal are more relevant and complete than answers without one. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. @@ -145,14 +145,14 @@ This documentation is published with GitBook. GitBook is the documentation platf ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. -Perform an HTTP GET request on the current page URL with the \`ask\` query parameter, and the optional \`goal\` query parameter: +Perform an HTTP GET request on the current page URL with the \`ask\` and \`goal\` query parameters: \`\`\` GET ${pageUrl}?ask=&goal= \`\`\` \`ask\` is the immediate question: it should be specific, self-contained, and written in natural language. -\`goal\` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. +\`goal\` is the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal, so answers with a goal are more relevant and complete than answers without one. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. From d832a54689a71a3201b8bdb88652482e34ccb4b7 Mon Sep 17 00:00:00 2001 From: Steven H Date: Wed, 30 Sep 2026 10:08:44 +0100 Subject: [PATCH 2/5] prompt update --- packages/gitbook/src/routes/markdownPage.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/gitbook/src/routes/markdownPage.ts b/packages/gitbook/src/routes/markdownPage.ts index 228fd12bc9..c8ffcc59e8 100644 --- a/packages/gitbook/src/routes/markdownPage.ts +++ b/packages/gitbook/src/routes/markdownPage.ts @@ -96,7 +96,7 @@ GET ${context.linker.toAbsoluteURL( \`\`\` \`ask\` is the immediate question: it should be specific, self-contained, and written in natural language. -\`goal\` is the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal, so answers with a goal are more relevant and complete than answers without one. +\`goal\` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with \`ask=how do I create an API token\`, a goal like \`build a script that syncs our docs to a CMS\` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. @@ -152,7 +152,7 @@ GET ${pageUrl}?ask=&goal= \`\`\` \`ask\` is the immediate question: it should be specific, self-contained, and written in natural language. -\`goal\` is the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal, so answers with a goal are more relevant and complete than answers without one. +\`goal\` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with \`ask=how do I create an API token\`, a goal like \`build a script that syncs our docs to a CMS\` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. From d595716d6df48d317ad783721273321050ee225e Mon Sep 17 00:00:00 2001 From: Steven H Date: Thu, 1 Oct 2026 08:44:35 +0100 Subject: [PATCH 3/5] improve prompt --- packages/gitbook/src/lib/ask-prompt.ts | 7 +++++++ packages/gitbook/src/routes/markdownPage.ts | 7 +++---- 2 files changed, 10 insertions(+), 4 deletions(-) create mode 100644 packages/gitbook/src/lib/ask-prompt.ts diff --git a/packages/gitbook/src/lib/ask-prompt.ts b/packages/gitbook/src/lib/ask-prompt.ts new file mode 100644 index 0000000000..6e2307f038 --- /dev/null +++ b/packages/gitbook/src/lib/ask-prompt.ts @@ -0,0 +1,7 @@ +/** + * Describe the `ask` and `goal` query parameters of the ask endpoint, for agent-facing prompts. + */ +export function renderAskParametersDescription(): string { + return `\`ask\` is the immediate question: it should be specific, self-contained, and written in natural language. +\`goal\` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with \`ask=how do I create an API token\`, a goal like \`build a script that syncs our docs to a CMS\` lets GitBook tailor the answer to that use case.`; +} diff --git a/packages/gitbook/src/routes/markdownPage.ts b/packages/gitbook/src/routes/markdownPage.ts index c8ffcc59e8..5bfe7c3754 100644 --- a/packages/gitbook/src/routes/markdownPage.ts +++ b/packages/gitbook/src/routes/markdownPage.ts @@ -1,6 +1,7 @@ import type { RevisionPageDocument, RevisionPageGroup } from '@gitbook/api'; import { isAIEnabled } from '@/components/utils/isAIChatEnabled'; +import { renderAskParametersDescription } from '@/lib/ask-prompt'; import type { GitBookSiteContext } from '@/lib/context'; import { getExposableError } from '@/lib/data'; import { linkerWithMarkdownPages } from '@/lib/links'; @@ -95,8 +96,7 @@ GET ${context.linker.toAbsoluteURL( )}?ask=&goal= \`\`\` -\`ask\` is the immediate question: it should be specific, self-contained, and written in natural language. -\`goal\` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with \`ask=how do I create an API token\`, a goal like \`build a script that syncs our docs to a CMS\` lets GitBook tailor the answer to that use case. +${renderAskParametersDescription()} The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. @@ -151,8 +151,7 @@ Perform an HTTP GET request on the current page URL with the \`ask\` and \`goal\ GET ${pageUrl}?ask=&goal= \`\`\` -\`ask\` is the immediate question: it should be specific, self-contained, and written in natural language. -\`goal\` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with \`ask=how do I create an API token\`, a goal like \`build a script that syncs our docs to a CMS\` lets GitBook tailor the answer to that use case. +${renderAskParametersDescription()} The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. From 7551e7e15a15f9a91e17eca19927dcff21c0a75f Mon Sep 17 00:00:00 2001 From: Steven H Date: Thu, 1 Oct 2026 08:45:07 +0100 Subject: [PATCH 4/5] changeset --- .changeset/nice-cooks-melt.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/nice-cooks-melt.md diff --git a/.changeset/nice-cooks-melt.md b/.changeset/nice-cooks-melt.md new file mode 100644 index 0000000000..87454a67b0 --- /dev/null +++ b/.changeset/nice-cooks-melt.md @@ -0,0 +1,5 @@ +--- +"gitbook": patch +--- + +Improve the prompt for agents to ask questions. From 05945f4b5336b39bcf87617a06f042c8c1243812 Mon Sep 17 00:00:00 2001 From: Steven H Date: Thu, 1 Oct 2026 08:54:22 +0100 Subject: [PATCH 5/5] lint --- packages/gitbook/src/lib/ask-prompt.ts | 17 +++++++++++ packages/gitbook/src/routes/markdownPage.ts | 31 ++++++--------------- 2 files changed, 25 insertions(+), 23 deletions(-) diff --git a/packages/gitbook/src/lib/ask-prompt.ts b/packages/gitbook/src/lib/ask-prompt.ts index 6e2307f038..f6c2aebe95 100644 --- a/packages/gitbook/src/lib/ask-prompt.ts +++ b/packages/gitbook/src/lib/ask-prompt.ts @@ -5,3 +5,20 @@ export function renderAskParametersDescription(): string { return `\`ask\` is the immediate question: it should be specific, self-contained, and written in natural language. \`goal\` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with \`ask=how do I create an API token\`, a goal like \`build a script that syncs our docs to a CMS\` lets GitBook tailor the answer to that use case.`; } + +/** + * Render the "Querying This Documentation" section of the agent instructions. + * `pageUrl` is the URL of the current page, which the `ask` and `goal` parameters are appended to. + */ +export function renderQueryingDocumentation(options: { pageUrl: string }): string { + const { pageUrl } = options; + return `Perform an HTTP GET request on the following URL with the \`ask\` and \`goal\` query parameters: + +\`\`\` +GET ${pageUrl}?ask=&goal= +\`\`\` + +${renderAskParametersDescription()} + +The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.`; +} diff --git a/packages/gitbook/src/routes/markdownPage.ts b/packages/gitbook/src/routes/markdownPage.ts index 5bfe7c3754..7fb8138ee5 100644 --- a/packages/gitbook/src/routes/markdownPage.ts +++ b/packages/gitbook/src/routes/markdownPage.ts @@ -1,7 +1,7 @@ import type { RevisionPageDocument, RevisionPageGroup } from '@gitbook/api'; import { isAIEnabled } from '@/components/utils/isAIChatEnabled'; -import { renderAskParametersDescription } from '@/lib/ask-prompt'; +import { renderQueryingDocumentation } from '@/lib/ask-prompt'; import type { GitBookSiteContext } from '@/lib/context'; import { getExposableError } from '@/lib/data'; import { linkerWithMarkdownPages } from '@/lib/links'; @@ -70,6 +70,11 @@ function renderNotFoundMarkdown(context: GitBookSiteContext, pagePath: string) { const fullContentUrl = context.linker.toAbsoluteURL( context.linker.toPathInSite('llms-full.txt') ); + const askPageUrl = context.linker.toAbsoluteURL( + context.linker.toPathForPagePath({ + path: similarPages[0]?.path ?? 'docs/example', + }) + ); return `# Page Not Found @@ -86,19 +91,7 @@ If the exact page cannot be found, you can still retrieve the information using ### Option 1 — Ask a question (recommended) -Perform an HTTP GET request on the documentation index with the \`ask\` and \`goal\` parameters: - -\`\`\` -GET ${context.linker.toAbsoluteURL( - context.linker.toPathForPagePath({ - path: similarPages[0]?.path ?? 'docs/example', - }) - )}?ask=&goal= -\`\`\` - -${renderAskParametersDescription()} - -The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. +${renderQueryingDocumentation({ pageUrl: askPageUrl })} ### Option 2 — Browse the documentation index @@ -145,15 +138,7 @@ This documentation is published with GitBook. GitBook is the documentation platf ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. -Perform an HTTP GET request on the current page URL with the \`ask\` and \`goal\` query parameters: - -\`\`\` -GET ${pageUrl}?ask=&goal= -\`\`\` - -${renderAskParametersDescription()} - -The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. +${renderQueryingDocumentation({ pageUrl })} Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections. `;