Spaces:
Sleeping
Sleeping
| # LM Studioss — Tools.md | |
| **File Name:** `Tools.md` | |
| **System:** LMA Agent | |
| **Layer:** Tool Definition Layer | |
| **Version:** v1.0 | |
| **Purpose:** Define the approved tools LMA can use, what each tool does, when each tool should be used, and what rules control tool behavior. | |
| --- | |
| ## 1. Purpose of Tools.md | |
| `Tools.md` is the official tool-governance file for LMA. | |
| This file does **not** replace memory, identity, or agent behavior files. It defines what tools are available to the agent and how those tools should be used. | |
| ### Layer Separation | |
| * `AGENTS.md` defines **who LMA is** and how LMA should behave. | |
| * `Tools.md` defines **what LMA can use** to complete tasks. | |
| * Memory files define **what LMA can remember**. | |
| * Code files define **how LMA executes** the tool calls. | |
| --- | |
| ## 2. Global Tool Rules | |
| All tools must follow these rules: | |
| 1. Do not fabricate data. | |
| 2. Do not assume live or current information without using a verified live-data tool. | |
| 3. If a tool fails, report the failure clearly. | |
| 4. If no verified source is available, say so plainly. | |
| 5. Do not overwrite memory unless the user clearly requests it or the system rules allow it. | |
| 6. Do not run destructive code or file operations without explicit approval. | |
| 7. Keep tool responses structured and readable. | |
| 8. Use the least powerful tool needed for the task. | |
| 9. Prefer verified data over guessed data. | |
| 10. Stay aligned with LM Studioss governance and the Motion Cycle operating style. | |
| --- | |
| ## 3. Tool Definition Format | |
| Each tool must follow this structure: | |
| ```markdown | |
| ### Tool: ToolName | |
| Description: | |
| Brief explanation of what the tool does. | |
| Use When: | |
| - When this tool should be used. | |
| Do Not Use When: | |
| - When this tool should not be used. | |
| Input: | |
| - field_name (type): Description of input. | |
| Output: | |
| - field_name (type): Description of output. | |
| Rules: | |
| - Tool-specific rule. | |
| - Tool-specific rule. | |
| Failure Behavior: | |
| - What LMA should say or do if the tool fails. | |
| ``` | |
| --- | |
| # 4. Core LMA Tools | |
| --- | |
| ## Tool: TaskRouter | |
| Description: | |
| Determines what type of request the user made and routes the task to the proper tool, process, or response mode. | |
| Use When: | |
| * A user request may require memory, live data, validation, code, file handling, or structured reasoning. | |
| * LMA needs to decide whether a tool should be used. | |
| Do Not Use When: | |
| * The user is making simple conversation. | |
| * The answer can be given directly without tool support. | |
| Input: | |
| * request (string): The user’s current request. | |
| Output: | |
| * route (string): The selected route, process, or tool. | |
| * reason (string): Short reason for the selected route. | |
| Rules: | |
| * Identify user intent before selecting tools. | |
| * Do not route to tools unnecessarily. | |
| * Do not create tool loops. | |
| * If no tool applies, respond directly. | |
| Failure Behavior: | |
| * Return: `No valid tool route found. Responding directly.` | |
| --- | |
| ## Tool: MemoryReader | |
| Description: | |
| Reads stored memory from the LMA memory layer. | |
| Use When: | |
| * The user asks about previously saved information. | |
| * LMA needs known user preferences, project details, or system context. | |
| * The request depends on stored identity, project history, or saved rules. | |
| Do Not Use When: | |
| * The user gives all needed information in the current message. | |
| * The information is not stored in memory. | |
| Input: | |
| * key (string): The memory key or topic to retrieve. | |
| Output: | |
| * value (string): The stored memory content. | |
| * found (boolean): Whether the memory was found. | |
| Rules: | |
| * Read only. | |
| * Do not invent memory. | |
| * If memory is missing, say it is missing. | |
| * Do not expose private system memory unless allowed by the user-facing rules. | |
| Failure Behavior: | |
| * Return: `Memory key not found.` | |
| --- | |
| ## Tool: MemoryWriter | |
| Description: | |
| Writes new information or updates existing information in the LMA memory layer. | |
| Use When: | |
| * The user clearly asks LMA to remember something. | |
| * A system update must be stored for future operation. | |
| * A project milestone needs to be logged. | |
| Do Not Use When: | |
| * The information is temporary. | |
| * The user has not asked for it to be saved. | |
| * The data is sensitive and the user has not clearly requested storage. | |
| Input: | |
| * key (string): Memory key to create or update. | |
| * value (string): Information to store. | |
| * mode (string): `create`, `update`, or `append`. | |
| Output: | |
| * status (string): Confirmation of memory action. | |
| Rules: | |
| * Do not overwrite important memory without confirmation. | |
| * Store concise, durable information. | |
| * Keep memory organized by project or category. | |
| * Avoid saving clutter. | |
| Failure Behavior: | |
| * Return: `Memory write failed. No memory was changed.` | |
| --- | |
| ## Tool: LiveDataFetcher | |
| Description: | |
| Retrieves verified live or current data from approved sources. | |
| Use When: | |
| * The user asks for current news, weather, sports, prices, scores, schedules, laws, software updates, or any information that may have changed recently. | |
| Do Not Use When: | |
| * The request is historical, reflective, creative, or based on information already provided by the user. | |
| Input: | |
| * query (string): The live-data request. | |
| * category (string): `news`, `weather`, `sports`, `finance`, `software`, `general`, or `other`. | |
| Output: | |
| * data (string): Verified current information. | |
| * source (string): Source or source label. | |
| * timestamp (string): Retrieval time if available. | |
| Rules: | |
| * Never guess live data. | |
| * Always prefer verified sources. | |
| * If data cannot be verified, say so. | |
| * Label current data clearly. | |
| Failure Behavior: | |
| * Return: `No verified live data available.` | |
| --- | |
| ## Tool: SearchFallback | |
| Description: | |
| Runs a secondary search when the primary live-data or retrieval tool fails. | |
| Use When: | |
| * LiveDataFetcher fails. | |
| * A primary source is unavailable. | |
| * LMA needs backup verification. | |
| Do Not Use When: | |
| * Primary verified data is already available. | |
| * The request does not require current or external information. | |
| Input: | |
| * query (string): The fallback search request. | |
| Output: | |
| * results (string): Fallback search result summary. | |
| * confidence (string): `high`, `medium`, or `low`. | |
| Rules: | |
| * Label fallback results clearly. | |
| * Do not treat fallback data as stronger than primary verified data. | |
| * Report uncertainty. | |
| Failure Behavior: | |
| * Return: `Fallback search failed. No verified result found.` | |
| --- | |
| ## Tool: SourceVerifier | |
| Description: | |
| Checks whether retrieved information is supported by a reliable source. | |
| Use When: | |
| * LMA retrieves external information. | |
| * The topic may be current, sensitive, technical, legal, medical, financial, or high-impact. | |
| Do Not Use When: | |
| * The user is asking for creative writing, personal reflection, or general explanation that does not require external facts. | |
| Input: | |
| * claim (string): The statement to verify. | |
| * source_data (string): Source content or citation data. | |
| Output: | |
| * verification_status (string): `verified`, `partially verified`, or `not verified`. | |
| * notes (string): Explanation of verification result. | |
| Rules: | |
| * Do not mark unsupported claims as verified. | |
| * Prefer official or primary sources when possible. | |
| * Flag uncertainty clearly. | |
| Failure Behavior: | |
| * Return: `Verification failed. Claim should not be treated as confirmed.` | |
| --- | |
| ## Tool: CodeExecutor | |
| Description: | |
| Executes safe code in a controlled environment. | |
| Use When: | |
| * The user asks LMA to test code, calculate with code, process structured data, or generate code-based output. | |
| Do Not Use When: | |
| * The code may damage files, delete data, expose secrets, or perform unsafe operations. | |
| Input: | |
| * code (string): Code to execute. | |
| * language (string): Programming language. | |
| * purpose (string): Reason for execution. | |
| Output: | |
| * result (string): Execution result. | |
| * errors (string): Error output if any. | |
| Rules: | |
| * Do not execute destructive commands. | |
| * Do not access secrets or credentials. | |
| * Return exact error messages when possible. | |
| * Explain what failed in plain language. | |
| Failure Behavior: | |
| * Return: `Code execution failed.` followed by the error message. | |
| --- | |
| ## Tool: FileReader | |
| Description: | |
| Reads approved project files so LMA can understand existing code, configuration, documentation, or data. | |
| Use When: | |
| * The user asks LMA to inspect a file. | |
| * LMA needs to understand current project structure. | |
| * A code or documentation change depends on file contents. | |
| Do Not Use When: | |
| * The user has not provided or approved access to the file. | |
| * The file may contain secrets that are not needed. | |
| Input: | |
| * file_path (string): Path to the file. | |
| Output: | |
| * content (string): File content. | |
| * status (string): Read status. | |
| Rules: | |
| * Read only unless paired with FileWriter by user approval. | |
| * Do not expose secrets unnecessarily. | |
| * Summarize long files before making changes. | |
| Failure Behavior: | |
| * Return: `File could not be read.` | |
| --- | |
| ## Tool: FileWriter | |
| Description: | |
| Creates or updates approved project files. | |
| Use When: | |
| * The user explicitly asks LMA to create or modify a file. | |
| * LMA has enough context to make a safe edit. | |
| Do Not Use When: | |
| * The change is unclear. | |
| * The file is critical and no backup exists. | |
| * The user has not authorized writing. | |
| Input: | |
| * file_path (string): Target file path. | |
| * content (string): New or updated content. | |
| * mode (string): `create`, `overwrite`, or `append`. | |
| Output: | |
| * status (string): Write status. | |
| * file_path (string): Updated file path. | |
| Rules: | |
| * Prefer creating backups before overwriting. | |
| * Preserve indentation and formatting. | |
| * Do not delete existing content unless instructed. | |
| * Show what changed when possible. | |
| Failure Behavior: | |
| * Return: `File write failed. No changes were made.` | |
| --- | |
| ## Tool: ValidationEngine | |
| Description: | |
| Reviews outputs, code, documents, or data for correctness, structure, and rule alignment. | |
| Use When: | |
| * LMA produces important content. | |
| * A response must be checked for accuracy, format, or governance alignment. | |
| * Code or configuration changes need review. | |
| Do Not Use When: | |
| * The task is simple and low-risk. | |
| Input: | |
| * content (string): Content to validate. | |
| * validation_type (string): `accuracy`, `format`, `safety`, `governance`, or `code`. | |
| Output: | |
| * status (string): `pass`, `warning`, or `fail`. | |
| * issues (list): Problems found. | |
| * recommendations (list): Suggested fixes. | |
| Rules: | |
| * Flag missing steps. | |
| * Identify unclear assumptions. | |
| * Do not approve unverifiable claims. | |
| * Keep feedback specific and actionable. | |
| Failure Behavior: | |
| * Return: `Validation could not be completed.` | |
| --- | |
| ## Tool: BriefingGenerator | |
| Description: | |
| Generates structured briefings from live data, saved memory, or user-provided topics. | |
| Use When: | |
| * The user asks for a daily briefing, project briefing, AI briefing, sports briefing, or structured summary. | |
| Do Not Use When: | |
| * The user asks a simple direct question. | |
| Input: | |
| * topic (string): Briefing topic. | |
| * sources (list): Approved data sources or memory sources. | |
| * format (string): Desired briefing format. | |
| Output: | |
| * briefing (string): Structured briefing response. | |
| Rules: | |
| * Separate verified live data from memory-based context. | |
| * Mark missing data clearly. | |
| * Keep sections organized. | |
| * Do not overfill the briefing with unnecessary detail. | |
| Failure Behavior: | |
| * Return: `Briefing could not be generated because required data was unavailable.` | |
| --- | |
| ## Tool: PromptRefiner | |
| Description: | |
| Refines raw user prompts into clearer, more structured prompts while preserving the user’s intent. | |
| Use When: | |
| * The user asks to polish, strengthen, submit, refine, or prepare a prompt. | |
| * The request falls under LM Studioss prompt-development workflows. | |
| Do Not Use When: | |
| * The user asks for a direct answer and does not request prompt refinement. | |
| Input: | |
| * raw_prompt (string): User’s original prompt. | |
| * mode (string): `standard`, `client_safe`, `motion_cycle`, or `technical`. | |
| Output: | |
| * refined_prompt (string): Improved prompt. | |
| * notes (string): Optional explanation of changes. | |
| Rules: | |
| * Preserve the original intent. | |
| * Do not overcomplicate simple prompts. | |
| * Follow active LM Studioss framework rules. | |
| * If Gate Phrase is used, follow the required protocol exactly. | |
| Failure Behavior: | |
| * Return: `Prompt refinement failed. Original prompt preserved.` | |
| --- | |
| ## Tool: GovernanceChecker | |
| Description: | |
| Checks whether an action, output, or tool use aligns with LM Studioss governance rules. | |
| Use When: | |
| * LMA is about to perform a high-impact action. | |
| * A workflow involves memory, files, external tools, live data, or client-facing output. | |
| Do Not Use When: | |
| * The request is simple conversation or low-risk. | |
| Input: | |
| * action (string): Proposed action. | |
| * context (string): Relevant user or system context. | |
| Output: | |
| * status (string): `approved`, `needs review`, or `blocked`. | |
| * reason (string): Governance explanation. | |
| Rules: | |
| * Preserve user control. | |
| * Prevent unauthorized writes, deletions, or assumptions. | |
| * Keep client-safe outputs clean. | |
| * Follow LM Studioss operating boundaries. | |
| Failure Behavior: | |
| * Return: `Governance check failed. Action should pause for review.` | |
| --- | |
| ## Tool: ErrorHandler | |
| Description: | |
| Interprets errors and explains what happened in plain language. | |
| Use When: | |
| * A tool, script, API, file operation, or agent process fails. | |
| Do Not Use When: | |
| * There is no error to interpret. | |
| Input: | |
| * error_message (string): Raw error message. | |
| * context (string): What LMA was trying to do. | |
| Output: | |
| * explanation (string): Plain-language explanation. | |
| * likely_cause (string): Most likely cause. | |
| * next_step (string): Recommended fix. | |
| Rules: | |
| * Do not hide errors. | |
| * Do not blame the user. | |
| * Explain clearly and calmly. | |
| * Offer the safest next step. | |
| Failure Behavior: | |
| * Return: `Error could not be interpreted. Show raw error message.` | |
| --- | |
| ## Tool: AuditLogger | |
| Description: | |
| Logs important actions, tool calls, memory updates, and file changes. | |
| Use When: | |
| * LMA writes memory. | |
| * LMA modifies files. | |
| * LMA executes code. | |
| * LMA generates briefings or governance-sensitive outputs. | |
| Do Not Use When: | |
| * The user is having simple conversation. | |
| Input: | |
| * event_type (string): Type of event. | |
| * details (string): Summary of what happened. | |
| * timestamp (string): Time of event. | |
| Output: | |
| * status (string): Log status. | |
| Rules: | |
| * Keep logs concise. | |
| * Do not store unnecessary sensitive information. | |
| * Log actions, not private reasoning. | |
| * Use consistent timestamps. | |
| Failure Behavior: | |
| * Return: `Audit logging failed. Continue only if logging is not required.` | |
| --- | |
| # 5. Recommended Tool Use Flow | |
| For most requests, LMA should follow this order: | |
| 1. Read the user request. | |
| 2. Use TaskRouter if tool selection is needed. | |
| 3. Use MemoryReader if stored context is required. | |
| 4. Use LiveDataFetcher if current information is required. | |
| 5. Use SourceVerifier when external facts are used. | |
| 6. Use CodeExecutor or File tools only when required. | |
| 7. Use ValidationEngine for important outputs. | |
| 8. Use AuditLogger for meaningful system actions. | |
| 9. Respond clearly to the user. | |
| --- | |
| # 6. Source Layer Language | |
| When live data is used, LMA should label the response with a source layer note when appropriate. | |
| Examples: | |
| ```text | |
| Source Layer: Verified live data retrieved. | |
| ``` | |
| ```text | |
| Source Layer: No verified live data available. | |
| ``` | |
| ```text | |
| Source Layer: Memory-based response only. | |
| ``` | |
| ```text | |
| Source Layer: User-provided information only. | |
| ``` | |
| --- | |
| # 7. Tool Failure Standard | |
| If any tool fails, LMA must avoid pretending the tool succeeded. | |
| Correct response style: | |
| ```text | |
| I could not verify that with the available tool. | |
| ``` | |
| ```text | |
| The tool returned no usable result, so I will not guess. | |
| ``` | |
| ```text | |
| No verified live data available. | |
| ``` | |
| Incorrect response style: | |
| ```text | |
| Here is what probably happened... | |
| ``` | |
| ```text | |
| I assume the answer is... | |
| ``` | |
| ```text | |
| It should be current... | |
| ``` | |
| --- | |
| # 8. Tools Reserved for Future Versions | |
| These tools are not active unless implemented in code. | |
| ## Future Tool: TelegramConnector | |
| Purpose: | |
| Connect LMA to Telegram messaging workflows. | |
| Status: | |
| Reserved. | |
| --- | |
| ## Future Tool: WhatsAppConnector | |
| Purpose: | |
| Connect LMA to WhatsApp messaging workflows. | |
| Status: | |
| Reserved. | |
| --- | |
| ## Future Tool: CalendarReader | |
| Purpose: | |
| Read calendar events for scheduling and briefings. | |
| Status: | |
| Reserved. | |
| --- | |
| ## Future Tool: EmailDraftHelper | |
| Purpose: | |
| Draft emails from user instructions. | |
| Status: | |
| Reserved. | |
| --- | |
| ## Future Tool: ReportBuilder | |
| Purpose: | |
| Generate structured reports, PDFs, summaries, or client-safe documents. | |
| Status: | |
| Reserved. | |
| --- | |
| # 9. Final Rule | |
| Tools are helpers, not decision-makers. | |
| LMA must remain under user control, LM Studioss governance, and verified execution boundaries. | |
| **End of Tools.md v1.0** | |