Skip to content

improve: enhance tool descriptions for better LLM agent tool selection #319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
spidershield-contrib wants to merge 1 commit into
base: main
Choose a base branch
from
Open

improve: enhance tool descriptions for better LLM agent tool selection #319

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions apps/ai-gateway/src/tools/ai-gateway.tools.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import type { AIGatewayMCP } from '../ai-gateway.app'
export function registerAIGatewayTools(agent: AIGatewayMCP) {
agent.server.tool(
'list_gateways',
'List Gateways',
'List all Cloudflare Magic WAN gateways in your account. Use when the user wants to view, inspect, or manage network gateway configurations for Magic WAN connectivity. Accepts `account_id` (optional, uses active account if not specified). e.g., retrieving gateway details for network troubleshooting or configuration review. Do not use when you need to list other Cloudflare services like D1 databases or R2 buckets (use their respective list tools instead). Returns an error if the account lacks Magic WAN entitlements or API permissions.',
{
page: pageParam,
per_page: perPageParam,
Expand Down Expand Up @@ -59,7 +59,7 @@ export function registerAIGatewayTools(agent: AIGatewayMCP) {
}
)

agent.server.tool('list_logs', 'List Logs', ListLogsParams, async (params) => {
agent.server.tool('list_logs', 'List logs from Cloudflare services and applications in your account. Use when the user wants to review, monitor, or troubleshoot system events, errors, or activity across Cloudflare products. Do not use when you need to query structured data from D1 databases (use d1_database_query instead). Accepts `service` (optional, specifies which Cloudflare service), `limit` (optional, number of entries), and `start_time` (optional, timestamp filter). e.g., service="workers", limit=100. Raises an error if the specified service does not exist or if you lack permissions to access the logs.', ListLogsParams, async (params) => {
try {
const accountId = await agent.getActiveAccountId()
if (!accountId) {
Expand Down Expand Up @@ -107,7 +107,7 @@ export function registerAIGatewayTools(agent: AIGatewayMCP) {

agent.server.tool(
'get_log_details',
'Get a single Log details',
'Retrieve detailed information for a specific log entry from your Cloudflare account. Use when the user wants to examine the full details, metadata, or properties of an individual log record. Do not use when you need to search or list multiple logs (use search tools instead). Accepts `log_id` (required) to identify the specific log entry, e.g., log_id="abc123-def456-ghi789". Raises an error if the log ID does not exist or access is denied."abc123-def456-ghi789". Returns error if the log ID does not exist or access is denied. Do not use when you need to search or filter multiple logs (use appropriate search tools instead).',
{
gateway_id: GatewayIdParam,
log_id: LogIdParam,
Expand Down Expand Up @@ -157,7 +157,7 @@ export function registerAIGatewayTools(agent: AIGatewayMCP) {

agent.server.tool(
'get_log_request_body',
'Get Log Request Body',
'Retrieve the body content of a specific log request entry. Use when the user wants to examine the detailed payload or content data from a logged request for debugging or analysis purposes. Accepts `request_id` (required) and `format` (optional). e.g., request_id="abc123", format="json". Raises an error if the request_id does not exist or the log entry has no body content. Do not use when you need to search or list multiple log entries (use appropriate search tools instead)."12345", format="json". Do not use when you need to list multiple log entries (use a log listing tool instead). Raises an error if the request ID does not exist or is inaccessible.',
{
gateway_id: GatewayIdParam,
log_id: LogIdParam,
Expand Down Expand Up @@ -207,7 +207,7 @@ export function registerAIGatewayTools(agent: AIGatewayMCP) {

agent.server.tool(
'get_log_response_body',
'Get Log Response Body',
'Retrieve the response body content from Cloudflare logs for detailed inspection and debugging. Use when the user wants to examine the actual HTTP response data, payload content, or troubleshoot API responses from logged requests. Do not use when you need to search general Cloudflare documentation (use search_cloudflare_documentation instead). Accepts `log_id` (required) and `response_format` (optional). e.g., log_id="abc123def456". Raises an error if the log ID does not exist or access is denied."abc123def456" with response_format="json". Do not use when you need to view request headers or metadata (use other log inspection tools instead). Raises an error if the log entry does not exist or access permissions are insufficient.',
{
gateway_id: GatewayIdParam,
log_id: LogIdParam,
Expand Down
6 changes: 3 additions & 3 deletions apps/autorag/src/tools/autorag.tools.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import type { AutoRAGMCP } from '../autorag.app'
export function registerAutoRAGTools(agent: AutoRAGMCP) {
agent.server.tool(
'list_rags',
'List AutoRAGs (vector stores)',
'List all AutoRAGs (vector stores) in your Cloudflare account. Use when the user wants to view, browse, or inventory existing vector databases for AI applications. Do not use when you need to search documentation or query specific databases (use search_cloudflare_documentation or d1_database_query instead). Accepts `account_id` (optional, uses active account if not specified). e.g., returns vector stores like "my-embeddings-db" or "product-search-vectors". Raises an error if the account lacks AutoRAG access or API authentication fails. "customer-support-kb" or "product-docs-embeddings". Raises an error if no active account is set or if the account lacks AutoRAG access permissions.',
{
page: pageParam,
per_page: perPageParam,
Expand Down Expand Up @@ -73,7 +73,7 @@ export function registerAutoRAGTools(agent: AutoRAGMCP) {

agent.server.tool(
'search',
'Search Documents using AutoRAG (vector store)',
'Search documents using AutoRAG vector store to find relevant content based on semantic similarity. Use when the user wants to find information, answers, or relevant passages from indexed documents using natural language queries. Do not use when you need to search Cloudflare-specific documentation (use search_cloudflare_documentation instead). Accepts `query` (required string) for the search terms, e.g., "machine learning best practices" or "API authentication methods". Returns error if no documents are indexed in the vector store. "How to configure SSL certificates" or "database migration best practices". Returns error if the vector store is not initialized or the query is empty.',
{
rag_id: z.string().describe('ID of the AutoRAG to search'),
query: z.string().describe('Query to search for. Can be a URL, a title, or a snippet.'),
Expand Down Expand Up @@ -139,7 +139,7 @@ export function registerAutoRAGTools(agent: AutoRAGMCP) {

agent.server.tool(
'ai_search',
'AI Search Documents using AutoRAG (vector store)',
'Search documents using AutoRAG vector store to find semantically relevant content. Use when the user wants to find information, answers, or relevant passages from indexed documents using natural language queries. Do not use when you need to search Cloudflare-specific documentation (use search_cloudflare_documentation instead). Accepts `query` (required string) for the search terms, e.g., "machine learning best practices" or "API authentication methods". Raises an error if the vector store is not initialized or the query is empty. "How to configure SSL certificates" or "database migration best practices". Returns error if the vector store is not initialized or the query is empty.',
{
rag_id: z.string().describe('ID of the AutoRAG to search'),
query: z.string().describe('Query to search for. Can be a URL, a title, or a snippet.'),
Expand Down
6 changes: 3 additions & 3 deletions apps/browser-rendering/src/tools/browser.tools.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import type { BrowserMCP } from '../browser.app'
export function registerBrowserTools(agent: BrowserMCP) {
agent.server.tool(
'get_url_html_content',
'Get page HTML content',
'Retrieve the HTML content of a web page or URL. Use when the user wants to scrape, analyze, or inspect the raw HTML source code of a website or web page. Do not use when you need to search Cloudflare's official documentation (use search_cloudflare_documentation instead). Accepts `url` (required string), e.g., "https://example.com" or "https://blog.cloudflare.com/workers-ai". Raises an error if the URL is unreachable or returns a non-HTML response. "https://example.com" or "https://docs.cloudflare.com/workers/". Do not use when you need to search Cloudflare-specific documentation (use search_cloudflare_documentation instead). Returns the complete HTML markup as a string. Raises an error if the URL is unreachable or returns a non-HTML response.',
{
url: z.string().url(),
},
Expand Down Expand Up @@ -57,7 +57,7 @@ export function registerBrowserTools(agent: BrowserMCP) {

agent.server.tool(
'get_url_markdown',
'Get page converted into Markdown',
'Retrieve and convert a web page into Markdown format for easier reading and processing. Use when the user wants to extract clean, formatted text content from a website or URL for analysis, documentation, or content review. Do not use when you need to search Cloudflare-specific documentation (use search_cloudflare_documentation instead). Accepts `url` (required string), e.g., "https://example.com/article". Raises an error if the URL is inaccessible or returns non-HTML content. "https://example.com/article" or "https://docs.cloudflare.com/workers/". Do not use when you need to search Cloudflare-specific documentation (use search_cloudflare_documentation instead). Returns error if the URL is inaccessible or the page cannot be converted to Markdown format.',
{
url: z.string().url(),
},
Expand Down Expand Up @@ -107,7 +107,7 @@ export function registerBrowserTools(agent: BrowserMCP) {

agent.server.tool(
'get_url_screenshot',
'Get page screenshot',
'Capture a screenshot of a web page at a specified URL. Use when the user wants to visually inspect, document, or verify the appearance of a website or web application. Do not use when you need to search or read Cloudflare documentation content (use search_cloudflare_documentation instead). Accepts `url` (required) and optional parameters like `viewport_width`, `viewport_height`, and `full_page` for complete page capture. e.g., url="https://example.com", viewport_width=1920, full_page=true. Raises an error if the URL is unreachable or the page fails to load within the timeout period."https://example.com" with full_page=true for entire page screenshots. Returns an error if the URL is inaccessible, times out, or contains invalid formatting. Do not use when you need to search Cloudflare documentation content (use search_cloudflare_documentation instead).',
{
url: z.string().url(),
viewport: z
Expand Down
22 changes: 11 additions & 11 deletions apps/cloudflare-one-casb/src/tools/integrations.tools.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ const assetCategoryIdParam = z.string().describe('The UUID of the asset category
const toolDefinitions: Array<ToolDefinition<any>> = [
{
name: 'integration_by_id',
description: 'Analyze Cloudflare One Integration by ID',
description: 'Analyze a specific Cloudflare One Integration by its unique identifier to retrieve detailed configuration, status, and settings. Use when the user wants to inspect or troubleshoot a particular integration's setup, connection status, or configuration details. Accepts `integration_id` (required), e.g., "f47ac10b-58cc-4372-a567-0e02b2c3d479". Do not use when you need to list all available integrations (use a list integrations tool instead). Raises an error if the integration ID does not exist or access is denied.'s properties, connection details, or operational status. Accepts `integration_id` (required string), e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890". Do not use when you need to list all available integrations (use a general listing tool instead). Raises an error if the integration ID does not exist or you lack permissions to access it.',
params: { integrationIdParam },
handler: async ({
integrationIdParam,
Expand All @@ -50,7 +50,7 @@ const toolDefinitions: Array<ToolDefinition<any>> = [
},
{
name: 'integrations_list',
description: 'List all Cloudflare One Integrations in a given account',
description: 'List all Cloudflare One Integrations configured in a specified Cloudflare account. Use when the user wants to review, audit, or manage existing security integrations and identity providers. Accepts `account_id` (required) to specify which account to query. e.g., account_id="f1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6". Do not use when you need to view general account information (use accounts_list instead). Raises an error if the account ID is invalid or you lack permissions to access Cloudflare One settings.',
params: {},
handler: async ({ accountId, apiToken }: { accountId: string; apiToken: string }) => {
const { integrations } = await handleIntegrations({ accountId, apiToken })
Expand All @@ -59,7 +59,7 @@ const toolDefinitions: Array<ToolDefinition<any>> = [
},
{
name: 'assets_search',
description: 'Search Assets by keyword',
description: 'Search for Cloudflare assets by keyword across your account. Use when the user wants to find specific resources, services, or configurations by name or description. Accepts `keyword` (required string) to match against asset names, descriptions, or metadata, e.g., "worker-api" or "production-bucket". Do not use when you need to list all assets of a specific type (use the dedicated list tools like r2_buckets_list or d1_databases_list instead). Returns error if the search keyword is empty or the account context is not set.',
params: { assetSearchTerm },
handler: async ({
assetSearchTerm,
Expand All @@ -81,7 +81,7 @@ const toolDefinitions: Array<ToolDefinition<any>> = [
},
{
name: 'asset_by_id',
description: 'Search Assets by ID',
description: 'Retrieve detailed information about a specific Cloudflare asset using its unique identifier. Use when the user wants to inspect properties, configuration, or metadata of a particular asset they already know the ID for. Accepts `asset_id` (required string), e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890". Do not use when you need to search for assets by name or list all available assets (use appropriate listing tools instead). Returns error if the asset ID does not exist or you lack permissions to access it.',
params: { assetIdParam },
handler: async ({
assetIdParam,
Expand All @@ -102,7 +102,7 @@ const toolDefinitions: Array<ToolDefinition<any>> = [
},
{
name: 'assets_by_integration_id',
description: 'Search Assets by Integration ID',
description: 'Search for assets associated with a specific integration identifier in your Cloudflare account. Use when the user wants to find or filter assets that belong to a particular integration or service connection. Accepts `integration_id` (required string), e.g., "abc123-def456-ghi789". Do not use when you need to list all assets without filtering (use a general asset listing tool instead). Returns an error if the integration ID does not exist or you lack permissions to view the associated assets.',
params: { integrationIdParam },
handler: async ({
integrationIdParam,
Expand All @@ -124,7 +124,7 @@ const toolDefinitions: Array<ToolDefinition<any>> = [
},
{
name: 'assets_by_category_id',
description: 'Search Assets by Asset Category ID',
description: 'Search for assets filtered by a specific asset category identifier. Use when the user wants to find or retrieve assets that belong to a particular category within their Cloudflare account. Accepts `category_id` (required) to filter results by the asset category. e.g., category_id="web-security" or category_id="performance-tools". Returns an error if the category ID does not exist or is invalid. Do not use when you need to list all available asset categories (use a category listing tool instead).',
params: { assetCategoryIdParam },
handler: async ({
assetCategoryIdParam,
Expand All @@ -146,7 +146,7 @@ const toolDefinitions: Array<ToolDefinition<any>> = [
},
{
name: 'assets_list',
description: 'Paginated list of Assets',
description: 'List all assets in your Cloudflare account with pagination support. Use when the user wants to browse, review, or inventory their Cloudflare assets across services. Accepts `page` (optional, integer for pagination) and `per_page` (optional, number of results per page). e.g., page=2, per_page=50 to get the second page with 50 assets. Returns an error if the account lacks proper permissions to view assets. Do not use when you need details about a specific asset type like D1 databases or R2 buckets (use their respective list tools instead).',
params: {},
handler: async ({ accountId, apiToken }: { accountId: string; apiToken: string }) => {
const { assets } = await handleAssets({
Expand All @@ -159,7 +159,7 @@ const toolDefinitions: Array<ToolDefinition<any>> = [
},
{
name: 'asset_categories_list',
description: 'List Asset Categories',
description: 'List all available asset categories in your Cloudflare account. Use when the user wants to browse or review the different types of assets that can be managed within Cloudflare services. Do not use when you need to list specific assets within a category (use the appropriate asset-specific list tool instead). Accepts optional filtering parameters such as `account_id` if multiple accounts are configured. e.g., retrieving categories like "domains", "workers", "pages", or "r2_buckets". Raises an error if the active account is not properly configured or lacks sufficient permissions.',
params: {},
handler: async ({ accountId, apiToken }: { accountId: string; apiToken: string }) => {
const { categories } = await handleAssetCategories({
Expand All @@ -171,7 +171,7 @@ const toolDefinitions: Array<ToolDefinition<any>> = [
},
{
name: 'asset_categories_by_vendor',
description: 'List asset categories by vendor',
description: 'List asset categories organized by vendor in your Cloudflare account. Use when the user wants to browse or review available asset types grouped by their respective vendors. Accepts `vendor` (optional filter) and `category_type` (optional filter). e.g., vendor="cloudflare" or category_type="security". Returns an error if the account lacks proper permissions to view asset categories. Do not use when you need to list specific assets within a category (use a dedicated asset listing tool instead).',
params: { assetCategoryVendorParam },
handler: async ({
assetCategoryVendorParam,
Expand All @@ -192,7 +192,7 @@ const toolDefinitions: Array<ToolDefinition<any>> = [
},
{
name: 'asset_categories_by_type',
description: 'Search Asset Categories by type',
description: 'Search asset categories filtered by a specific type within your Cloudflare account. Use when the user wants to find or browse asset categories that match a particular classification or category type. Accepts `type` (required string) to filter categories, e.g., "security" or "performance". Do not use when you need to list all asset categories without filtering (use a general asset listing tool instead). Raises an error if the specified type does not exist or if account access is insufficient.',
params: { assetCategoryTypeParam },
handler: async ({
assetCategoryTypeParam,
Expand All @@ -213,7 +213,7 @@ const toolDefinitions: Array<ToolDefinition<any>> = [
},
{
name: 'asset_categories_by_vendor_and_type',
description: 'Search Asset Categories by vendor and type',
description: 'Search asset categories filtered by vendor and type within your Cloudflare account. Use when the user wants to find specific asset categories based on vendor name or asset type criteria. Accepts `vendor` (optional string) and `type` (optional string) parameters for filtering results. e.g., vendor="Microsoft" or type="software". Returns an error if the account context is not properly set. Do not use when you need to list all accounts or set the active account (use accounts_list or set_active_account instead).',
params: { assetCategoryTypeParam, assetCategoryVendorParam },
handler: async ({
assetCategoryTypeParam,
Expand Down
Loading