> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/reference/mcp-tools-and-prompts.md). # MCP Tools and Prompts The concrete tools, built-in prompts, and OAuth scopes the Heeler MCP server exposes to your AI coding agent — each with an example call. When you connect the [Heeler MCP server](/mrecEO40m5D6bt7Pq5pE/prevent/mcp.md), your AI coding agent gains a set of **tools** for pulling live security context from Heeler and a set of **built-in prompts** for running consistent, repeatable security reviews. This page is the catalog — every tool and prompt below expands to show an example call. Tools that take a repository scope accept **`repository_id`**, and **`repository_ids`** where the tool takes a list. `entities_search` resolves a name you have to the id you pass. Five tools also accept a full **`repository_url`** and resolve it across GitHub, GitLab, Bitbucket and Azure DevOps: `service_risk_brief`, `get_sast_results_for_file`, `get_vulnerabilities_for_project`, `get_endpoint_security_context_for_project` and `get_deployment_exposure_for_project`. Those five and the guardrail tools also accept **`repository_name`**, a plain name Heeler matches and asks you to confirm when it is ambiguous. Every tool rejects a property it does not declare, so a `repository_url` sent to a tool that takes only `repository_id` returns `invalid_arguments` before the tool runs. Filter values are **OR within a field, AND across fields**. {% hint style="info" %} The JSON below is illustrative and abbreviated — real responses include additional fields, and the exact keys depend on the finding type. Where a tool paginates, use the returned `next_cursor` with `page.cursor` to page through larger result sets. {% endhint %} ## Tools ### Findings and triage
findings_search — search findings across any scope and filter The primary workhorse for triage. Scope by repository/team/service/application/environment and narrow with status, priority, CVSS, SLO, and source-type filters; supports stable sorting, facets, and cursor pagination. `source_type` covers dependency (`SCA`), static analysis (`SAST`), and `SECRET` findings. Agent files are a separate asset class and are not returned here — see [Agent-file governance](#agent-file-governance). Within native findings, `finding_type` narrows to one family: `IAC` for [Infrastructure as Code](/mrecEO40m5D6bt7Pq5pE/findings/iac.md) misconfigurations, `CICD_CONFIG` for [CI/CD Config](/mrecEO40m5D6bt7Pq5pE/findings/cicd-config.md) findings, and `SAST` for everything else. Native findings carry their `finding_type`, and any of those three values can be passed back as a filter. Dependency and secret findings return `null` for it. The filter applies to native findings only: a request that sets it returns no dependency or secret findings. Omit it and `source_type: ["SAST"]` returns all three families. **Example** — *"show me the overdue critical dependency findings in payments-api"*: ```json { "repository_id": "h4r>>github>>github_repository>>acme>>payments-api", "filters": { "source_type": ["SCA"], "cvss_severity": ["CRITICAL"], "slo_state": ["OVERDUE"], "status": ["OPEN"] }, "sort": { "field": "slo_due_date", "direction": "asc" }, "page": { "limit": 20 } } ``` Returns findings (each with the id you'd pass to `finding_details`), facets, and a page cursor: ```json { "findings": [ { "id": "fnd_9Qp2mK", "source_type": "SCA", "title": "Prototype pollution in lodash < 4.17.21", "priority": "P0", "cvss_severity": "CRITICAL", "slo_state": "OVERDUE", "package": { "name": "lodash", "installed": "4.17.15", "fixed_in": "4.17.21" }, "location": "services/payments-api/package-lock.json" } ], "facets": { "priority": { "P0": 1, "P1": 3 } }, "page": { "next_cursor": "eyJvIjoyMH0" } } ``` **Example** — *"show me the IaC misconfigurations in payments-api"*: ```json { "repository_id": "h4r>>github>>github_repository>>acme>>payments-api", "filters": { "source_type": ["SAST"], "finding_type": ["IAC"], "status": ["OPEN"] }, "page": { "limit": 20 } } ```
findings_counts — aggregate counts by scope and filter Answers "how many …" questions. Returns SCA/SAST/secret counts for a scope with optional severity, status, and `auto_fixable` filters. Add `finding_type` to narrow the SAST count to one native family, using the same `IAC` / `CICD_CONFIG` / `SAST` values as `findings_search`. `finding_type` restricts the response to native findings, so the dependency and secret counts come back as `0`. Leave it out when you want the counts across all three sources. **Example** — *"how many open SAST findings does the payments team have?"*: ```json { "team": ["payments"], "source_type": ["SAST"], "status": ["OPEN"] } ``` ```json { "counts": { "SAST": { "OPEN": 42, "CRITICAL": 3, "HIGH": 11 } } } ```
findings_trend — finding counts over time Timeseries of opened/closed findings for a scope and date window — use it for "are we trending down?" questions. **Example** — *"chart the payments-api finding trend over the last 90 days"*: ```json { "repository_id": "h4r>>github>>github_repository>>acme>>payments-api", "days": 90, "severity": ["CRITICAL", "HIGH"] } ```
finding_details — a single finding's full detail Drill into one finding: canonical fields plus SLO, remediation, and history sections. **Example** — take an id from `findings_search`: ```json { "finding_id": "fnd_9Qp2mK" } ```
slo_queue — what's approaching or past its SLO The operational queue of overdue and due-soon findings, with an optional grouped rollup by team, repository, owner, or service. **Example** — *"what's overdue or due in the next 7 days, grouped by team?"*: ```json { "window": { "due_within_days": 7, "overdue_only": false }, "group_by": "team", "include_items": true } ```
portfolio_posture_summary — a leadership snapshot across the estate Open risk, due-soon SLOs, and top hot spots for a scope and time window — the answer to broad "what should we worry about?" questions. **Example** — whole-estate snapshot over the last 30 days: ```json { "time_window_days": 30 } ```
### Vulnerabilities and packages
vulnerabilities_lookup — find where a CVE exists Given a CVE or advisory id, returns where it exists across repositories, services, teams, applications, and environments, including open/closed status. **Example** — *"where do we have CVE-2021-23337?"*: ```json { "cve": "CVE-2021-23337" } ```
vulnerability_details — a vulnerability's full detail and blast radius CVE-centric blast radius and urgency in one call — severity, exploit signals, and impacted scope. **Example**: ```json { "cve": "CVE-2021-23337" } ```
package_investigation — a package's usage and supply-chain risk Package blast radius: where it's used, impacted repositories and services, and urgent open vulnerability context. Package name must be exact (no fuzzy matching). **Example** — *"investigate our exposure to lodash"*: ```json { "package_name": "lodash" } ```
vulnerable_package_inventory — an exportable inventory of vulnerable packages An exportable inventory of vulnerable package finding instances — package, CVE, current version, recommended fix, and manifest path — for reporting and upgrade-planning tables. Results are **cursor-paginated** (follow `page_info.next_cursor` until `has_more` is false); for a downloadable CSV, use `create_csv_export` instead. Optional `package_name` and `vulnerability_id` filters narrow the scope. **Example** — first page of vulnerable packages for one team: ```json { "team": ["payments"], "limit": 100 } ``` ```json { "packages": [ { "name": "lodash", "installed": "4.17.15", "fixed_in": "4.17.21", "cve": "CVE-2021-23337", "manifest": "package-lock.json" } ], "page_info": { "has_more": false, "next_cursor": null } } ```
get_vulnerabilities_for_project — dependency vulnerabilities for a repository Active dependency vulnerabilities (with remediation hints when available) for one repository. Pass a plain name as `repository_name` if that's all you have. **Example**: ```json { "repository_url": "https://github.com/acme/payments-api" } ```
### Code, endpoints and runtime
get_sast_results_for_file — SAST findings for the file you're editing Code findings scoped to a single file path, grouped by severity with suggested fixes — built for in-editor use as you touch a file. **Example** — the agent passes the file it's editing: ```json { "repository_url": "https://github.com/acme/payments-api", "file_path": "auth/session.py" } ``` ```json { "file": "auth/session.py", "findings": [ { "rule": "sql-injection", "severity": "HIGH", "line": 42, "weakness": "User input concatenated into a SQL statement", "suggested_fix": "Use a parameterized query" } ], "counts": { "HIGH": 1 } } ```
get_endpoint_security_context_for_project — endpoint auth & exposure The API attack surface for a repository — which routes exist and which are authenticated or internet-accessible. **Example**: ```json { "repository_url": "https://github.com/acme/payments-api" } ```
get_deployment_exposure_for_project — what's deployed and reachable Deployment exposure signals (internet accessibility, runtime), unresolved secrets, and urgent dependency context — so the agent triages by real exposure, not just severity. **Example**: ```json { "repository_url": "https://github.com/acme/payments-api" } ```
### Services and portfolio
service_summary — operational posture for a service Finding counts, deployment context, and exposure signals for a service or scope — the answer to "is this service internet-accessible and how much risk does it carry?". **Example**: ```json { "service_name": "payments-api", "environment": "production" } ```
service_risk_brief — an analyst brief for a service A one-call brief: trend, exposure, top fix actions, and exploit-chain risk scoring. Choose a `scoring_profile` to tune how aggressively chains are scored. **Example**: ```json { "service": ["payments-api"], "window_days": 30, "scoring_profile": "balanced" } ```
entities_search — resolve an ambiguous repository / service / team name Call this first when a name is partial, misspelled, or ambiguous; it returns candidate entities to disambiguate before calling a scoped tool. **Example** — *"which repos match 'payment'?"*: ```json { "query": "payment", "limit": 10 } ``` ```json { "candidates": [ { "type": "repository", "name": "payments-api", "repository_id": "h4r>>github>>github_repository>>acme>>payments-api" }, { "type": "service", "name": "payments-worker" } ] } ```
### Remediation planning
remediation_groups — the fixes that close the most findings Fix-many planning: groups changes by highest-impact remediation action (package upgrade, upgrade action, or rule), which identifies the single upgrades that clear the most findings. **Example** — upgrades that each close at least 3 findings for a team: ```json { "team": ["payments"], "grouping": "package", "min_findings_closed": 3 } ```
remediation_counts — aggregate remediation counts Counts active Heeler remediation records by repository-assigned **team** or **repository** (`group_by`, default `team`) — for capacity planning and exportable totals. Team attribution follows repository ownership, so a remediation on a multi-team repository counts once per assigned team. **Example** — remediations per repository for one team: ```json { "team": ["payments"], "group_by": "repository" } ```
### Guardrails and SLOs
guardrail_list — every configured guardrail Lists guardrails with their rules, action (Block / Warn / Notify), scope, and pass rate. Use `include_scope_detail` to resolve repository-scoped guardrails to human-readable repo names. **Example** — *"which guardrails are in block mode?"*: ```json { "action": "Block", "enabled_only": true, "include_scope_detail": true } ```
guardrail_execution_stats — how guardrails are performing Two modes: omit `bucket` for per-guardrail pass rate, fail count, trend, and top failing repos/contributors; set `bucket` to `day`/`week`/`month` for a time-series. **Example** — weekly portfolio pass-rate trend: ```json { "bucket": "week", "since": "2026-05-01" } ```
guardrail_pr_status — the full guardrail picture for one PR Which guardrails ran on a PR, what violations they found, and whether those were resolved before merge. Look up by `pr_url` (most reliable) or `repository_name` + `pr_identifier`. **Example** — *"why was PR #847 blocked?"*: ```json { "pr_url": "https://github.com/acme/payments-api/pull/847" } ``` ```json { "result": "blocked", "guardrails": [ { "name": "No Critical CVEs", "action": "Block", "violations": 1, "resolved_before_merge": false } ] } ```
guardrail_finding_status — is a vulnerability covered by a guardrail? Which guardrails cover a given CVE, finding, or violation type, and whether they've historically fired. Use `match_confidence` in the result to know if one will fire — don't infer. **Example** — *"would CVE-2024-1234 be blocked in payments-api?"*: ```json { "vuln_id": "CVE-2024-1234", "repository_name": "payments-api" } ```
guardrail_observe_impact — what-if analysis for Notify-mode guardrails Shows what would happen if a Notify (observe) guardrail were switched to Block — the key signal is how many PRs merged with unresolved violations out of total merged PRs. **Example** — *"is it safe to switch 'Payments Watch' to block?"*: ```json { "guardrail_id": "Payments Watch", "since": "2026-05-01" } ```
guardrail_blocked_prs — PRs blocked or merged-with-violations PR-level summary of what guardrails stopped, with contributor and which guardrails fired. Use `status=currently_blocked` for open blockers or `status=merged_with_violations` for a risk register. **Example** — *"what PRs merged with violations this month?"*: ```json { "status": "merged_with_violations", "since": "2026-07-01" } ```
guardrail_violations — a flat list of individual violations Every individual violation with full PR context in one call — violation type, file, detail, the guardrail that fired, and PR info. Preferred over chaining `guardrail_blocked_prs` + `guardrail_pr_status`. **Example** — *"list secrets detected across the payments team this month"*: ```json { "team": ["payments"], "violation_type": "secret", "since": "2026-07-01" } ```
### Agent-file governance {% hint style="info" %} Agent files are a **separate asset class**, not a finding type. They're scored by a judge verdict (benign / suspicious / malicious) rather than a severity, and they carry no SLO. That means they never appear in `findings_search`, `findings_counts`, `findings_trend`, or `portfolio_posture_summary` — an empty result from those tools is not evidence that you have no agent-file risk. Use the two tools below instead. {% endhint %}
agent_files_list — AI agent instruction files Heeler has scored Lists agent instruction files, skills, subagents, and MCP configuration (`CLAUDE.md`, `.cursorrules`, `.mcp.json`, skill directories), with risk scores. Filter to `at_risk` only, or by assessed intent (benign / suspicious / malicious). **Example** — *"show the at-risk agent files, worst first"*: ```json { "at_risk": true, "sort": "score", "direction": "desc", "limit": 50 } ``` **Risk counts** — the response carries a `total` alongside the page of results, so you don't need to page through everything to count. Ask for a single row and read `total`: ```json { "at_risk": true, "limit": 1 } ``` Add `assessed_intent`, `repository_id`, or `kind` to count a subset the same way. For a full extract rather than a count, use `create_csv_export` with `"export_type": "agent_files"`.
agent_file_details — the evidence behind one agent file's score Full assessment for a single agent file or bundle: score breakdown, static findings, LLM findings, and invocation context. Pass the `instance_id` from `agent_files_list`. **Example**: ```json { "instance_id": 10432 } ```
### Documentation
docs_search — search Heeler's product documentation Searches Heeler's published product documentation and returns relevant excerpts with source links, so the assistant can answer "how does Heeler do X?" grounded in the docs. **Example** — *"how do I set up a pre-commit hook?"*: ```json { "query": "set up pre-commit hook" } ``` ```json { "matches": [ { "title": "CLI", "url": "https://docs.heeler.com/prevent/cli", "excerpt": "Install the pre-commit hook with `heelercli install-hook`, which runs secrets and dependency checks on staged changes…" } ] } ```
### Reporting and export
create_csv_export → get_csv_export_status — asynchronous CSV export Export is a two-step, asynchronous pattern. First create an export (findings, SAST findings, dependencies, licenses, secrets, services, deployments, endpoints, repositories, violations, agent files…): ```json { "export_name": "payments-api criticals", "export_type": "findings", "repository_id": "h4r>>github>>github_repository>>acme>>payments-api", "fix_status": "active" } ``` It returns an export id and a `pending` status: ```json { "ok": true, "export_id": "exp_7bQ1nD", "export_type": "findings", "status": "pending" } ``` Then poll `get_csv_export_status` with that id until it's `completed`, which returns a time-limited download URL: ```json { "export_id": "exp_7bQ1nD" } ``` ```json { "ok": true, "export_id": "exp_7bQ1nD", "status": "completed", "row_count": 128, "download_url": "https://…", "download_url_expires_in_seconds": 3600 } ``` {% hint style="info" %} Exports run against **your** visible scope, so a non-admin's export contains only what they can see. The download URL is short-lived — re-poll `get_csv_export_status` to mint a fresh one. {% endhint %}
### Overrides and remediation *(mutations)*
slo_overrides_list / slo_overrides_create / slo_overrides_extend — manage SCA SLO overrides View and manage dependency-finding SLO/risk overrides. **List first** to confirm the target, then create or extend. Create and extend are immediate mutations that write an audit note and require **admin + `heeler:write:overrides`**. List active overrides expiring soon: ```json { "expiring_within_days": 14 } ``` Set a new due date for a finding: ```json { "finding_id": 480021, "slo_due_date": "2026-09-30T00:00:00Z", "reason": "VENDOR_FIX_PENDING", "description": "Awaiting upstream patch release" } ```
sast_slo_overrides_list / sast_slo_overrides_create / sast_slo_overrides_extend — manage SAST SLO overrides The same list / create / extend pattern for **native SAST** findings. Create and extend require **admin + `heeler:write:overrides`**. ```json { "finding_id": 771204, "slo_due_date": "2026-09-15T00:00:00Z", "reason": "COMPENSATING_CONTROL", "description": "WAF rule blocks the exploitable path" } ```
schedule_heeler_remediation — start the remediation agent Schedules Heeler's remediation agent to fix one or more dependency findings: it clones the repository, applies the upgrade, and opens a pull request. Returns execution UUIDs for tracking. Requires **admin + `heeler:execute:remediation`**. **Example** — fix two remediations, each as its own PR, held for review: ```json { "remediation_ids": [30581, 30590], "separate_prs": true, "auto_open_pr": false } ``` ```json { "executions": ["exec_a1B2c3", "exec_d4E5f6"], "status": "scheduled" } ```
## Built-in prompts Heeler registers **four named prompts** your assistant can invoke directly (via `prompts/get`). Each hands the assistant a structured analysis task grounded in your real data — more repeatable than an ad-hoc question. Invoke them by their **canonical name** (paraphrases may not resolve), typically through your client's prompt picker rather than as typed free text.
secure_development_checklist — implementation guidance for new endpoints Hands the assistant a secure-implementation checklist — triggered when you add endpoints or ask for a security checklist. The checklist steps are fixed guidance: identify existing endpoint patterns, match the auth controls similar endpoints use, validate inputs, run Heeler's SAST and dependency checks on what changed, and review common weakness classes. When the prompt resolves a repository, it also appends a snapshot of that repository's existing endpoints and their authentication status, so the assistant can match the patterns already in use. **Example** — select the prompt in your client's picker; for a resolved repository it produces: > Secure development checklist: > > 1. Identify existing endpoint patterns before adding new routes. > 2. Match authentication and authorization controls used by similar endpoints. > 3. Confirm new endpoints have explicit auth, input validation, and safe defaults. > 4. Use Heeler MCP `get_sast_results_for_file` for changed files and prioritize high/critical findings. > 5. Use Heeler MCP `get_vulnerabilities_for_project` to review active urgent dependency findings. > 6. Review for common weaknesses: IDOR/BOLA, broken access control, XSS, SQL/NoSQL injection, command injection, SSRF, path traversal, CSRF, open redirects, unsafe file upload, and secret exposure. > 7. Existing endpoint auth snapshot: > * Common auth protocols: jwt (6), api\_key (2) > * `POST /payments` -> protected > * `GET /transfers/{id}` -> unknown
secure_code_risk_review — weakness review of changed files Reviews changed files (and nearby modules) for common weaknesses — IDOR/BOLA, broken access control, XSS, SQL/NoSQL & command injection, SSRF, path traversal, insecure deserialization, CSRF, open redirects, auth/session flaws, unsafe uploads, sensitive-data exposure — and proposes concrete fixes and tests. **Example** — invoked on a diff, it reports: > Reviewed 4 changed files. > > * `api/orders.py:61` — **IDOR**: `order_id` is read from the path and queried without an ownership check. Add a `WHERE user_id = :current_user` guard. Suggested test included. > * `web/render.py:20` — **XSS**: user-supplied `note` is written into the template unescaped. > > Want me to apply the ownership-check fix and add the regression test?
heeler_sast_pass — a pre-commit SAST gate For each file you've touched it calls `get_sast_results_for_file`, summarizes active findings by severity, explains exploitability in the diff, and offers to remediate — a pre-commit gate rather than an ad-hoc search. **Example**: > Reviewed 3 changed files. **1 HIGH, 2 MEDIUM** active SAST findings. > > * `auth/session.py:42` — HIGH, SQL injection: user input concatenated into a query. Exploitable in this diff via the new `login()` path. > * `api/upload.py:88` — MEDIUM, path traversal on the upload filename. > > Want me to remediate the HIGH finding and add a regression test before you commit?
heeler_sca_dependency_guard — urgent dependency findings before merge Uses `get_vulnerabilities_for_project` to find urgent dependency findings, recommend safe upgrade targets, and prioritize critical/high before merge. **Example**: > **payments-api** has 2 urgent dependency findings: > > * `lodash 4.17.15` → **CVE-2021-23337** (CRITICAL). Safe target: `4.17.21`. > * `axios 0.21.0` → **CVE-2021-3749** (HIGH). Safe target: `0.21.2`. > > Both are direct dependencies. Want me to open the upgrade PR before you merge?
## Scopes The tools available depend on the OAuth scopes your token was granted: | Capability | Required scope | | ---------------------------------------------- | ------------------------------------------------ | | Search findings, view details, check SLOs | Read (`heeler:read`) | | Vulnerability and package lookups | Read (`heeler:read`) | | Service summaries, portfolio snapshots, trends | Read (`heeler:read`) | | SAST / SCA / deployment context for code files | Read (`heeler:read`) | | Guardrail status, violations, blocked PRs | Read (`heeler:read`) | | Generate CSV exports, search documentation | Read (`heeler:read`) | | Create and extend SLO overrides | **Administrator + `heeler:write:overrides`** | | Schedule agentic remediation | **Administrator + `heeler:execute:remediation`** | {% hint style="info" %} Most read tools accept either a `heeler:read` token or a scoped `heeler:scan:vulnerabilities` token (the latter is typically issued to automated scanners). But **`docs_search`, the two CSV export tools and the four built-in prompts require `heeler:read` specifically — a scan-only token cannot invoke them.** So `heeler:read` covers the entire read surface on its own, and `heeler:scan:vulnerabilities` grants nothing on top of it. The SLO-override and remediation tools require the **Administrator** role in addition to the write or execute scope. A **Team contributor** or **Organization contributor** can trigger a remediation in the web interface and gets `access_denied` over MCP. **Administrator (read-only)** is never issued the write or execute scopes, so they do not appear on its consent screen. {% endhint %} ## Errors and rate limits Tool input is validated against the schema shown by the MCP client before a handler runs. A tool-call failure is returned as an MCP `isError` result whose structured content includes a stable `code`, a safe `message`, and a server `request_id` for support correlation: | Code | Meaning | | ------------------- | ------------------------------------------------------------------------------------------------------------ | | `invalid_arguments` | A required argument is missing, an argument has the wrong type or value, or an undeclared property was sent. | | `not_found` | The requested entity does not exist or is not visible to this identity. | | `conflict` | A write precondition failed or a concurrent change won. | | `tool_error` | The tool could not complete a safe, expected domain operation. | | `internal_error` | An unexpected server failure occurred; internal details are withheld. | Role failures are HTTP `403` OAuth responses rather than tool errors. `access_denied` means the signed-in user needs the Administrator role for that tool. Scope failures depend on the call. A `tools/call` from an OAuth client returns HTTP `403` with `insufficient_scope` and the scope to ask for, which a client that supports authorization step-up can act on. `tools/list`, `prompts/list` and `prompts/get`, and any call from a client that did not authenticate over OAuth, return a JSON-RPC error inside an HTTP `200` response instead. MCP calls have their own budgets: one per verified principal for OAuth and browser-session callers, and a shared one per source network for callers Heeler has not verified. A `429` includes `Retry-After` plus `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. See [Rate Limits](/mrecEO40m5D6bt7Pq5pE/reference/rate-limits.md). ## Related * [MCP Server](/mrecEO40m5D6bt7Pq5pE/prevent/mcp.md) — what it does, editor-vs-chat context, and the common workflows. * [Rate Limits](/mrecEO40m5D6bt7Pq5pE/reference/rate-limits.md) — MCP principal budgets, API-key behavior, response headers, and the CSV export quota. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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: ``` GET https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/reference/mcp-tools-and-prompts.md?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. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. 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.