Custom tool descriptions

[aganonki]

What problem does this proposed feature solve?

Add ability to Override tools descriptions used in system prompt.

Currently there is no way to replace tool descriptions without overriding whole system prompt and if advanced user would like to compress/rewrite/change tool descriptions he has no way to do it.

For example i would like to use this to make tool calling prompts more light weight.
I tested custom reduced prompt versions that greatly reduce initial context buffer by 50% without significant quality loss if any.

Describe the proposed solution in detail

Add your description in .roo/tools/read_file.md it will override default read_file tool description with your provided description from file additionally it would supports args param replacement with ${args.cwd}

Technical considerations or implementation details (optional)

I already have code with tests ready for Draft

Describe alternatives considered (if any)

No response

Additional Context & Mockups

Example:

Proposal Checklist

• I have searched existing Issues and Discussions to ensure this proposal is not a duplicate.
• This proposal is for a specific, actionable change intended for implementation (not a general idea).
• I understand that this proposal requires review and approval before any development work begins.

Are you interested in implementing this feature if approved?

• Yes, I would like to contribute to implementing this feature.

[hannesrudolph]

I understand the motivation behind this suggestion, but my concern is that allowing users to fully override tool descriptions may discourage contributing these improvements back into Roo itself.

If your modified tool descriptions meaningfully improve tool calling (either reducing context, increasing output quality, or both), integrating them into Roo’s core prompts would benefit everyone. If you’re able to share your improved descriptions, I can run them through our evals to verify their effectiveness, which helps streamline their inclusion.

The existing system prompt override (“footgun prompting”) is intentionally a sandbox meant for experimentation and improvement, rather than permanent overrides.

Would you be able to provide your modified prompts for evaluation?

[aganonki]

@hannesrudolph I get what you mean but top models do not need a in depth explanation with repeatable examples and they can handle tool calling with straight forward instructions. For example: GPT 4.1 or Sonnet 4 - it is enough to have something like this in tool calling

THIS it is not enough for other MODELS (not TOP coding/development trained models).

Example

# TOOLS
## read_file
Description: Read file contents. Use for analyzing code, text files, or configs. Output includes line numbers. Extracts text from PDFs and DOCX. Not for other binary files.
Parameters: path (required) (relative to the current workspace directory ${args.cwd}), start_line (optional), end_line (optional)

## search_files
Description: Search files in a directory using regex. Shows matches with context. Useful for finding code patterns or specific content.
Parameters: path (required) (relative to the current workspace directory ${args.cwd}), regex (required), file_pattern (optional)

## list_files
Description: List files and directories. Can be recursive. Don’t use to check if files you created exist; user will confirm.
Parameters: path (required) (relative to the current workspace directory ${args.cwd}), recursive (optional)

## list_code_definition_names
Description: List top-level code definitions (classes, functions, etc.) in a directory. Helps understand codebase structure.
Parameters: path (required) (relative to the current workspace directory ${args.cwd})

## apply_diff: 
Description: Replace code in a file using a search and replace block. Must match existing content exactly. Use read_file first if unsure.
Parameters: path (required) (relative to the current workspace directory ${args.cwd}), diff (required)
Diff format:
'''
<<<<<<< SEARCH
:start_line: (required) The line number of original content where the search block starts.
-------
[exact content to find including whitespace]
=======
[new content to replace with]
>>>>>>> REPLACE

'''

Example Diff:
'''
<<<<<<< SEARCH
:start_line:1
-------
def calculate_total(items):
    total = 0
    for item in items:
        total += item
    return total
=======
def calculate_total(items):
    """Calculate total with 10% markup"""
    return sum(item * 1.1 for item in items)
>>>>>>> REPLACE

'''

## write_to_file
Description: Write full content to a file. Overwrites if exists, creates if not. MUST provide COMPLETE file content, not partial updates. MUST include app 3 parameters, path, content, and line_count
Parameters: path (required) (relative to the current workspace directory ${args.cwd}), content (required), line_count (required)

## search_and_replace
Description: Find and replace specific text strings or patterns (using regex) within a file. Supports literal text and regex patterns, case sensitivity options, and optional line ranges.
Parameters: path (required) (relative to the current workspace directory ${args.cwd}), search (required), replace (required), start_line (optional), end_line (optional), use_regex (optional), ignore_case (optional)

## insert_content
Description: Add new lines of content into a file without modifying existing content. Specify the line number to insert before, or use line 0 to append to the end.
Parameters: path (required) (relative to the current workspace directory ${args.cwd}), line (required), content (required)

## execute_command
Description: Run CLI commands. Explain what the command does. Prefer complex commands over scripts. Commands run in the current directory. To run in a different directory, use `cwd` parameter.
Parameters: command (required), cwd (optional)

## ask_followup_question
Description: Ask the user a question to get more information. Use when you need clarification or details.
Parameters: question (required)

## attempt_completion
Description: Present the task result to the user. Optionally provide a CLI command to demo the result. Don’t use it until previous tool uses are confirmed successful.
Parameters: result (required), command (optional)

# TOOL USE FORMATTING
IMPORTANT REPLACE actual_tool_name with the tool you want to use, for example read_file.
IMPORTANT REPLACE parameter_name with the parameter name, for example path.
Format tool use with XML tags, e.g.:

<actual_tool_name>
<parameter1_name>value1</parameter1_name>
<parameter2_name>value2</parameter2_name>
...
</actual_tool_name>

[hannesrudolph]

Before sending this up to dev for approval we would like to understand your technical implementation. Could you please link us your draft?