@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/raw/auth/workos.mdx

@@ -1,198 +0,0 @@
----
-title: "MastraAuthWorkos Class"
-description: "Documentation for the MastraAuthWorkos class, which authenticates Mastra applications using WorkOS authentication."
----
-
-import { Tabs, Tab } from "@/components/tabs";
-
-# MastraAuthWorkos Class
-
-The `MastraAuthWorkos` class provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the `experimental_auth` option.
-
-## Prerequisites
-
-This example uses WorkOS authentication. Make sure to:
-
-1. Create a WorkOS account at [workos.com](https://workos.com/)
-2. Set up an Application in your WorkOS Dashboard
-3. Configure your redirect URIs and allowed origins
-4. Set up Organizations and configure user roles as needed
-
-```env filename=".env" copy
-WORKOS_API_KEY=sk_live_...
-WORKOS_CLIENT_ID=client_...
-```
-
-> **Note:** You can find your API key and Client ID in the WorkOS Dashboard under API Keys and Applications respectively.
-
-> For detailed setup instructions, refer to the [WorkOS documentation](https://workos.com/docs) for your specific platform.
-
-## Installation
-
-Before you can use the `MastraAuthWorkos` class you have to install the `@mastra/auth-workos` package.
-
-```bash copy
-npm install @mastra/auth-workos@latest
-```
-
-## Usage examples
-
-### Basic usage with environment variables
-
-```typescript {2,7} filename="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
-import { MastraAuthWorkos } from '@mastra/auth-workos';
-
-export const mastra = new Mastra({
-  // ..
-  server: {
-    experimental_auth: new MastraAuthWorkos(),
-  },
-});
-```
-
-### Custom configuration
-
-```typescript {2,7-10} filename="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
-import { MastraAuthWorkos } from '@mastra/auth-workos';
-
-export const mastra = new Mastra({
-  // ..
-  server: {
-    experimental_auth: new MastraAuthWorkos({
-      apiKey: process.env.WORKOS_API_KEY,
-      clientId: process.env.WORKOS_CLIENT_ID
-    }),
-  },
-});
-```
-
-## Configuration
-
-### User Authorization
-
-By default, `MastraAuthWorkos` checks whether the authenticated user has an 'admin' role in any of their organization memberships. The authorization process:
-
-1. Retrieves the user's organization memberships using their user ID
-2. Extracts all roles from their memberships
-3. Checks if any role has the slug 'admin'
-4. Grants access only if the user has admin role in at least one organization
-
-To customize user authorization, provide a custom `authorizeUser` function:
-
-```typescript filename="src/mastra/auth.ts" showLineNumbers copy
-import { MastraAuthWorkos } from '@mastra/auth-workos';
-
-const workosAuth = new MastraAuthWorkos({
-  apiKey: process.env.WORKOS_API_KEY,
-  clientId: process.env.WORKOS_CLIENT_ID,
-  authorizeUser: async (user) => {
-    return !!user;
-  },
-});
-```
-
-> See the [MastraAuthWorkos](/reference/auth/workos) API reference for all available configuration options.
-
-## Client-side setup
-
-When using WorkOS auth, you'll need to implement the WorkOS authentication flow to exchange an authorization code for an access token, then use that token with your Mastra requests.
-
-### Installing WorkOS SDK
-
-First, install the WorkOS SDK in your application:
-
-```bash copy
-npm install @workos-inc/node
-```
-
-### Exchanging code for access token
-
-After users complete the WorkOS authentication flow and return with an authorization code, exchange it for an access token:
-
-```typescript filename="lib/auth.ts" showLineNumbers copy
-import { WorkOS } from '@workos-inc/node';
-
-const workos = new WorkOS(process.env.WORKOS_API_KEY);
-
-export const authenticateWithWorkos = async (code: string, clientId: string) => {
-  const authenticationResponse = await workos.userManagement.authenticateWithCode({
-    code,
-    clientId,
-  });
-
-  return authenticationResponse.accessToken;
-};
-```
-
-> Refer to the [WorkOS User Management documentation](https://workos.com/docs/authkit/vanilla/nodejs) for more authentication methods and configuration options.
-
-## Configuring `MastraClient`
-
-When `experimental_auth` is enabled, all requests made with `MastraClient` must include a valid WorkOS access token in the `Authorization` header:
-
-```typescript filename="lib/mastra/mastra-client.ts" showLineNumbers copy
-import { MastraClient } from "@mastra/client-js";
-
-export const createMastraClient = (accessToken: string) => {
-  return new MastraClient({
-    baseUrl: "https://<mastra-api-url>",
-    headers: {
-      Authorization: `Bearer ${accessToken}`
-    }
-  });
-};
-```
-
-> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
-
-> See [Mastra Client SDK](/docs/server-db/mastra-client) for more configuration options.
-
-### Making authenticated requests
-
-Once `MastraClient` is configured with the WorkOS access token, you can send authenticated requests:
-
-<Tabs items={["JavaScript/Node.js", "curl"]}>
-  <Tab>
-    ```typescript filename="src/api/agents.ts" showLineNumbers copy
-    import { WorkOS } from '@workos-inc/node';
-    import { MastraClient } from '@mastra/client-js';
-
-    const workos = new WorkOS(process.env.WORKOS_API_KEY);
-
-    export const callMastraWithWorkos = async (code: string, clientId: string) => {
-      const authenticationResponse = await workos.userManagement.authenticateWithCode({
-        code,
-        clientId,
-      });
-
-      const token = authenticationResponse.accessToken;
-
-      const mastra = new MastraClient({
-        baseUrl: "http://localhost:4111",
-        headers: {
-          Authorization: `Bearer ${token}`,
-        },
-      });
-
-      const weatherAgent = mastra.getAgent("weatherAgent");
-      const response = await weatherAgent.generate({
-        messages: "What's the weather like in Nairobi",
-      });
-
-      return response.text;
-    };
-    ```
-  </Tab>
-  <Tab>
-    ```bash copy
-    curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
-      -H "Content-Type: application/json" \
-      -H "Authorization: Bearer <your-workos-access-token>" \
-      -d '{
-        "messages": "Weather in London"
-      }'
-    ```
-  </Tab>
-</Tabs>

package/.docs/raw/community/contributing-templates.mdx

@@ -1,193 +0,0 @@
----
-title: "Contributing Templates"
-description: "How to contribute your own templates to the Mastra ecosystem"
----
-
-import { Callout } from "nextra/components";
-
-# Contributing Templates
-
-The Mastra community plays a vital role in creating templates that showcase innovative application patterns. This guide explains how to contribute your own templates to the Mastra ecosystem.
-
-## Template Contribution Process
-
-### 1. Review Requirements
-
-Before creating a template, ensure you understand:
-
-- [Templates Reference](/reference/templates) - Technical requirements and conventions
-- [Project Structure](/docs/getting-started/project-structure) - Standard Mastra project organization
-- Community guidelines and quality standards
-
-### 2. Develop Your Template
-
-Create your template following the established patterns:
-
-- Focus on a specific use case or pattern
-- Include comprehensive documentation
-- Test thoroughly with fresh installations
-- Follow all technical requirements
-- Ensure the github repo is a template repo. [How to create a template repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)
-
-### 3. Submit for Review
-
-Once your template is ready, submit it through our contribution form. Templates undergo an approval process to ensure quality and consistency.
-
-## Submission Guidelines
-
-### Template Criteria
-
-We accept templates that:
-
-- **Demonstrate unique value** - Show innovative use cases or patterns not covered by existing templates
-- **Follow conventions** - Adhere to all technical requirements and structural guidelines
-- **Include quality documentation** - Provide clear setup instructions and usage examples
-- **Work reliably** - Function correctly with minimal setup after installation
-
-### Quality Standards
-
-Templates must meet these quality benchmarks:
-
-- **Code quality** - Clean, well-commented, and maintainable code
-- **Error handling** - Proper error handling for external APIs and user inputs
-- **Type safety** - Full TypeScript typing with Zod validation where appropriate
-- **Documentation** - Comprehensive README with setup and usage instructions
-- **Testing** - Verified to work with fresh installations
-
-## Submission Process
-
-### 1. Prepare Your Template
-
-Ensure your template meets all requirements outlined in the [Templates Reference](/reference/templates):
-
-- Proper project structure in `src/mastra/` directory
-- Standard TypeScript configuration
-- Comprehensive `.env.example` file
-- Detailed README with setup instructions
-
-### 2. Submit Your Template
-
-Submit your template using our contribution form:
-
-**[Submit Template Contribution](https://forms.gle/g1CGuwFxqbrb3Rz57)**
-
-### Required Information
-
-When submitting your template, provide:
-
-- **Template Name** - Clear, descriptive name indicating the use case
-- **Template Author Name** - Your name or organization name
-- **Template Author Email** - Contact email for communication about your submission
-- **GitHub URL** - Link to your template repository
-- **Description** - Detailed explanation of what the template does and its value
-- **Optional Image** - Screenshot or diagram showing the template in action
-- **Optional Demo Video** - Link to a video demonstrating the template's functionality
-
-## Review Process
-
-### Review Criteria
-
-Templates are evaluated on:
-
-- **Technical compliance** - Adherence to template rules and conventions
-- **Code quality** - Clean, maintainable, and well-documented code
-- **Uniqueness** - Novel use cases or innovative implementation patterns
-- **Educational value** - Ability to teach Mastra concepts effectively
-- **Community benefit** - Potential value to the broader Mastra community
-
-### Feedback and Iteration
-
-If your template needs improvements:
-
-- You'll receive specific feedback on required changes
-- Make the requested modifications and resubmit
-- The review process continues until the template meets standards
-
-## Community Guidelines
-
-### Template Ideas
-
-Consider creating templates for:
-
-- **Industry-specific use cases** - Healthcare, finance, education, etc.
-- **Integration patterns** - Specific API or service integrations
-- **Advanced techniques** - Complex workflows, multi-agent systems, or novel patterns
-- **Learning resources** - Step-by-step tutorials for specific concepts
-
-### Development Best Practices
-
-- **Start simple** - Begin with a minimal working example and add complexity gradually
-- **Document thoroughly** - Include detailed comments and comprehensive README
-- **Test extensively** - Verify your template works across different environments
-- **Seek feedback** - Share with the community for early feedback before submission
-
-### Community Engagement
-
-- **Join Discord** - Participate in the [Mastra Discord community](https://discord.gg/BTYqqHKUrf)
-- **Share progress** - Update the community on your template development
-- **Help others** - Assist other contributors with their templates
-- **Stay updated** - Keep track of new Mastra features and conventions
-
-## Template Maintenance
-
-### Ongoing Responsibilities
-
-As a template contributor, you may be asked to:
-
-- **Update dependencies** - Keep templates current with latest Mastra versions
-- **Fix issues** - Address bugs or compatibility problems
-- **Improve documentation** - Enhance instructions based on user feedback
-- **Add features** - Extend templates with new capabilities
-
-### Community Support
-
-The Mastra team and community provide:
-
-- **Technical guidance** - Help with complex implementation challenges
-- **Review feedback** - Detailed feedback to improve template quality
-- **Promotion** - Showcase approved templates to the community
-- **Maintenance assistance** - Support for keeping templates up-to-date
-
-## Validation Checklist
-
-Before submitting a template, verify:
-
-- [ ] All code organized in `src/mastra/` directory
-- [ ] Uses standard Mastra TypeScript configuration
-- [ ] Includes comprehensive `.env.example`
-- [ ] Has detailed README with setup instructions
-- [ ] No monorepo or web framework boilerplate
-- [ ] Successfully runs after fresh install and environment setup
-- [ ] Follows all code quality standards
-- [ ] Demonstrates clear, valuable use case
-
-## Community Showcase
-
-### Template Gallery
-
-Approved templates will be featured in:
-
-- **mastra.ai/templates** - Community template gallery (coming soon)
-- **Documentation** - Referenced in relevant documentation sections
-- **Community highlights** - Featured in newsletters and community updates
-
-### Recognition
-
-Template contributors receive:
-
-- **Attribution** - Your name and contact information with the template
-- **Community recognition** - Acknowledgment in community channels
-
-## Getting Started
-
-Ready to contribute a template?
-
-1. **Explore existing templates** - Review current templates for inspiration and patterns
-2. **Plan your template** - Define the use case and value proposition
-3. **Follow the requirements** - Ensure compliance with all technical requirements
-4. **Build and test** - Create a working, well-documented template
-5. **Submit for review** - Use the contribution form to submit your template
-
-<Callout type="info">
-Your contributions help grow the Mastra ecosystem and provide valuable resources for the entire community. We look forward to seeing your innovative templates!
-</Callout>

package/.docs/raw/community/discord.mdx

@@ -1,12 +0,0 @@
----
-title: "Discord Community and Bot | Documentation | Mastra"
-description: Information about the Mastra Discord community and MCP bot.
----
-
-# Discord Community
-
-The Discord server has over 1000 members and serves as the main discussion forum for Mastra. The Mastra team monitors Discord during North American and European business hours, with community members active across other time zones.[Join the Discord server](https://discord.gg/BTYqqHKUrf).
-
-## Discord MCP Bot
-
-In addition to community members, we have an (experimental!) Discord bot that can also help answer questions. It uses [Model Context Protocol (MCP)](/docs/agents/mcp-guide). You can ask it a question with `/ask` (either in public channels or DMs) and clear history (in DMs only) with `/cleardm`.

package/.docs/raw/community/licensing.mdx

@@ -1,71 +0,0 @@
----
-title: "Licensing"
-description: "Mastra License"
----
-
-# License
-
-## Apache License 2.0
-
-Mastra is licensed under the Apache License 2.0, a permissive open-source license that provides users with broad rights to use, modify, and distribute the software.
-
-### What is Apache License 2.0?
-
-The Apache License 2.0 is a permissive open-source license that grants users extensive rights to use, modify, and distribute the software. It allows:
-
-- Free use for any purpose, including commercial use
-- Viewing, modifying, and redistributing the source code
-- Creating and distributing derivative works
-- Commercial use without restrictions
-- Patent protection from contributors
-
-The Apache License 2.0 is one of the most permissive and business-friendly open-source licenses available.
-
-### Why We Chose Apache License 2.0
-
-We selected the Apache License 2.0 for several important reasons:
-
-1. **True Open Source**: It's a recognized open-source license that aligns with open-source principles and community expectations.
-
-2. **Business Friendly**: It allows for unrestricted commercial use and distribution, making it ideal for businesses of all sizes.
-
-3. **Patent Protection**: It includes explicit patent protection for users, providing additional legal security.
-
-4. **Community Focus**: It encourages community contributions and collaboration without restrictions.
-
-5. **Widely Adopted**: It's one of the most popular and well-understood open-source licenses in the industry.
-
-### Building Your Business with Mastra
-
-The Apache License 2.0 provides maximum flexibility for building businesses with Mastra:
-
-#### Allowed Business Models
-
-- **Building Applications**: Create and sell applications built with Mastra
-- **Offering Consulting Services**: Provide expertise, implementation, and customization services
-- **Developing Custom Solutions**: Build bespoke AI solutions for clients using Mastra
-- **Creating Add-ons and Extensions**: Develop and sell complementary tools that extend Mastra's functionality
-- **Training and Education**: Offer courses and educational materials about using Mastra effectively
-- **Hosted Services**: Offer Mastra as a hosted or managed service
-- **SaaS Platforms**: Build SaaS platforms powered by Mastra
-
-#### Examples of Compliant Usage
-
-- A company builds an AI-powered customer service application using Mastra and sells it to clients
-- A consulting firm offers implementation and customization services for Mastra
-- A developer creates specialized agents and tools with Mastra and licenses them to other businesses
-- A startup builds a vertical-specific solution (e.g., healthcare AI assistant) powered by Mastra
-- A company offers Mastra as a hosted service to their customers
-- A SaaS platform integrates Mastra as their AI backend
-
-#### Compliance Requirements
-
-The Apache License 2.0 has minimal requirements:
-
-- **Attribution**: Maintain copyright notices and license information (including NOTICE file)
-- **State Changes**: If you modify the software, state that you have made changes
-- **Include License**: Include a copy of the Apache License 2.0 when distributing
-
-### Questions About Licensing?
-
-If you have specific questions about how the Apache License 2.0 applies to your use case, please [contact us](https://discord.gg/BTYqqHKUrf) on Discord for clarification. We're committed to supporting all legitimate use cases while maintaining the open-source nature of the project.

package/.docs/raw/course/01-first-agent/04-project-structure.md

@@ -1,17 +0,0 @@
-# Verifying Project Structure
-
-Let's check that your project has the correct structure. You should have:
-
-1. A `src/mastra` directory that contains:
-   - `index.ts` - The main entry point for your Mastra project
-   - `agents/` - Directory containing individual agent files
-   - `tools/` - Directory containing individual tool files
-   - `workflows/` - Directory containing individual workflow files
-
-If the CLI created your project, you should see files like:
-
-- `agents/weather-agent.ts` - Example weather agent
-- `tools/weather-tool.ts` - Example weather tool
-- `workflows/weather-workflow.ts` - Example weather workflow
-
-This structure is important because it follows the Mastra convention for organizing your code. The `index.ts` file is the main entry point for your Mastra project, while the `agents` and `tools` directories contain the definitions for your agents and tools, respectively.

package/.docs/raw/course/01-first-agent/05-running-playground.md

@@ -1,19 +0,0 @@
-# Running the Playground
-
-To test your agent as you build it, you'll need to run the Mastra playground:
-
-```bash
-npm run dev
-```
-
-This will start the playground at `http://localhost:4111/`, where you can interact with your agent and test its capabilities.
-
-The playground provides a user-friendly interface for testing your agent, allowing you to:
-
-- Send messages to your agent
-- See the agent's responses
-- View the agent's thought process
-- Test tools directly
-- Debug any issues that arise
-
-In the next step, we'll create our first agent with a simple system prompt and test it in the playground.

package/.docs/raw/course/01-first-agent/07-creating-your-agent.md

@@ -1,51 +0,0 @@
-# Creating Your Agent
-
-Let's create a simple agent that will help users analyze financial transaction data. We'll create a new file called `agents/financial-agent.ts`.
-
-First, create the new agent file at src/mastra/agents/financial-agent.ts
-
-Now add the necessary imports at the top of your file:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-// We'll import our tool in a later step
-```
-
-Now, let's create our agent:
-
-```typescript
-export const financialAgent = new Agent({
-  name: "Financial Assistant Agent",
-  instructions: `ROLE DEFINITION
-- You are a financial assistant that helps users analyze their transaction data.
-- Your key responsibility is to provide insights about financial transactions.
-- Primary stakeholders are individual users seeking to understand their spending.
-
-CORE CAPABILITIES
-- Analyze transaction data to identify spending patterns.
-- Answer questions about specific transactions or vendors.
-- Provide basic summaries of spending by category or time period.
-
-BEHAVIORAL GUIDELINES
-- Maintain a professional and friendly communication style.
-- Keep responses concise but informative.
-- Always clarify if you need more information to answer a question.
-- Format currency values appropriately.
-- Ensure user privacy and data security.
-
-CONSTRAINTS & BOUNDARIES
-- Do not provide financial investment advice.
-- Avoid discussing topics outside of the transaction data provided.
-- Never make assumptions about the user's financial situation beyond what's in the data.
-
-SUCCESS CRITERIA
-- Deliver accurate and helpful analysis of transaction data.
-- Achieve high user satisfaction through clear and helpful responses.
-- Maintain user trust by ensuring data privacy and security.`,
-  model: openai("gpt-4o"), // You can use "gpt-3.5-turbo" if you prefer
-  tools: {}, // We'll add tools in a later step
-});
-```
-
-This creates a financial assistant agent with a well-defined system prompt that outlines its role, capabilities, behavioral guidelines, constraints, and success criteria.

package/.docs/raw/course/01-first-agent/08-exporting-your-agent.md

@@ -1,33 +0,0 @@
-# Exporting Your Agent
-
-To make your agent available to the playground, you need to export it through the Mastra class in your `src/mastra/index.ts` file.
-
-First, import the necessary dependencies and your agent:
-
-```typescript
-import { Mastra } from "@mastra/core/mastra";
-import { PinoLogger } from "@mastra/loggers";
-import { LibSQLStore } from "@mastra/libsql";
-import { financialAgent } from "./agents/financial-agent";
-
-export const mastra = new Mastra({
-  agents: {
-    financialAgent,
-  },
-  storage: new LibSQLStore({
-    url: ":memory:",
-  }),
-  logger: new PinoLogger({
-    name: "Mastra",
-    level: "info",
-  }),
-});
-```
-
-This creates a new Mastra instance that includes:
-
-- Your financial agent
-- In-memory storage for development
-- A logger for debugging and monitoring
-
-The Mastra class is the main entry point for your Mastra project. It's responsible for registering your agents and configuring the core services like storage and logging.

package/.docs/raw/course/01-first-agent/09-testing-your-agent.md

@@ -1,12 +0,0 @@
-# Testing Your Agent
-
-Now let's test our agent in the playground:
-
-1. Make sure your development server is running with `npm run dev`
-2. Open the playground at http://localhost:4111/
-3. You should see your "Financial Assistant Agent" in the list of agents
-4. Try sending a message like "Hello, can you help me analyze my spending?"
-
-At this point, your agent can respond to basic questions but doesn't have access to any transaction data. In the next step, we'll create a custom tool to fetch transaction data from a Google Sheet.
-
-Testing your agent in the playground is an important step in the development process. It allows you to see how your agent responds to different inputs and identify any issues that need to be addressed before deploying it to production.

package/.docs/raw/course/01-first-agent/11-creating-transactions-tool.md

@@ -1,41 +0,0 @@
-# Creating the getTransactions Tool
-
-Let's create a tool that fetches transaction data from a Google Sheet. We'll create a new file called `tools/get-transactions-tool.ts`.
-
-First, create the new tool file at src/mastra/tools/get-transactions-tool.ts
-
-Now add the necessary imports:
-
-```typescript
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-```
-
-Now, let's create our tool:
-
-```typescript
-export const getTransactionsTool = createTool({
-  id: "get-transactions",
-  description: "Get transaction data from Google Sheets",
-  inputSchema: z.object({}), // No input parameters needed
-  outputSchema: z.object({
-    csvData: z.string(),
-  }),
-  execute: async () => {
-    return await getTransactions();
-  },
-});
-
-const getTransactions = async () => {
-  // This URL points to a public Google Sheet with transaction data
-  const url =
-    "https://docs.google.com/spreadsheets/d/e/2PACX-1vTQWaCzJAFsF4owWRHQRLo4G0-ERv31c74OOZFnqLiTLaP7NweoiX7IXvzQud2H6bdUPnIqZEA485Ux/pub?gid=0&single=true&output=csv";
-  const response = await fetch(url);
-  const data = await response.text();
-  return {
-    csvData: data,
-  };
-};
-```
-
-This tool fetches transaction data from a public Google Sheet and returns it as a string. The `createTool` function from Mastra makes it easy to define the tool's ID, description, input and output schemas, and execution logic.

package/.docs/raw/course/01-first-agent/12-connecting-tool-to-agent.md

@@ -1,29 +0,0 @@
-# Connecting the Tool to Your Agent
-
-Now that we've created our tool, we need to connect it to our agent. Go back to your `agents/financial-agent.ts` file and update it:
-
-1. Import the tool:
-
-```typescript
-import { getTransactionsTool } from "../tools/get-transactions-tool";
-```
-
-2. Add the tool to your agent:
-
-```typescript
-export const financialAgent = new Agent({
-  name: "Financial Assistant Agent",
-  instructions: `ROLE DEFINITION
-  // ... existing instructions ...
-  
-  TOOLS
-  - Use the getTransactions tool to fetch financial transaction data.
-  - Analyze the transaction data to answer user questions about their spending.`,
-  model: openai("gpt-4o"),
-  tools: { getTransactionsTool }, // Add our tool here
-});
-```
-
-By adding the tool to your agent's configuration, you're making it available for the agent to use. The agent will now be able to call the `getTransactions` tool when it needs to access transaction data.
-
-It's also important to update the agent's instructions to include information about the tool. This helps the agent understand when and how to use the tool to fulfill user requests.