Una capa de capacidades MCP (Model Context Protocol) independiente del repositorio para operaciones controladas en repositorios locales.
Cross Repo Ops MCP proporciona un servidor stdio JSON-RPC reforzado en seguridad que expone operaciones acotadas y controladas por políticas en repositorios git locales:
Lectura: listado de árbol, búsqueda con ripgrep, lecturas de archivos acotadas, git status/diff
Escritura: parches verificados por contexto con soporte de creación/modificación (solo repositorios con permiso de escritura)
Tareas: ejecución de tareas nombradas aprobadas (solo allowlist, sin shell arbitrario)
Git: listar/crear/cambiar ramas, commit (solo archivos explícitos), push (solo origin, solo repositorios con permiso de push)
Related MCP server: Coding Tools MCP
Cross Repo Ops MCP es una capa de capacidades independiente del repositorio para operaciones controladas en repositorios locales. Está diseñado para ubicarse junto a un proyecto XcodeIDEapp, tomando ideas de patrones de andamiaje de paneles de IDE, pero sigue siendo genérico y no depende de ningún IDE o estructura de proyecto específica.
Cross Repo Ops MCP = controlled local repository actions (read, patch, git, tasks)El servidor se basa en políticas: los repositorios, las capacidades, las rutas excluidas y las tareas aprobadas se declaran en una configuración JSON. No hay lógica específica del proyecto codificada en el núcleo.
Módulo | Responsabilidad |
| Política centralizada de capacidades del repositorio (allowlist, flags writable/pushable, rutas excluidas, allowlist de tareas, límites, timeouts) |
| Única frontera autoritativa de validación de rutas (comprobaciones de traversal, symlink, ruta absoluta y contención) |
| Listado de árbol, búsqueda con ripgrep, lectura de archivos acotada, git status/diff |
| Aplicación de parches verificados por contexto con soporte de creación/modificación |
| Operaciones de rama, commit y push con salvaguardas de seguridad |
| Resolución y ejecución de la allowlist de tareas nombradas |
| Servidor MCP stdio JSON-RPC |
| Tipos de error |
Allowlist de repositorios: Solo los repositorios explícitamente listados en la política son accesibles.
Flags de capacidad: writable y pushable son por repositorio, con valor predeterminado false.
Contención de rutas: Todas las rutas se resuelven y verifican contra la raíz del repositorio. Se rechazan traversal (..), rutas absolutas y symlinks.
Exclusión de archivos sensibles: .env, *.pem, claves de API, tokens, credenciales y archivos binarios están bloqueados para lectura y escritura.
Seguridad de parches: old_text debe coincidir exactamente; las coincidencias múltiples requieren context para desambiguar. create=true se niega a sobrescribir archivos existentes.
Allowlist de tareas: Las tareas se resuelven por nombre desde una allowlist del lado del servidor, no desde la entrada del usuario. No hay comandos de shell arbitrarios.
Seguridad de Git: Se rechaza el staging masivo (git add -A). Los commits se limitan a archivos explícitamente listados. Los archivos sensibles no se pueden incluir en commits. Los nombres de rama se validan contra inyección. El push se limita a origin solo para repositorios con permiso de push.
Límites de salida: Todas las operaciones tienen topes de salida configurables (caracteres de lectura, resultados de búsqueda, entradas de árbol, caracteres de diff, salida de tareas).
# No external dependencies required — Python 3.10+ standard library only.
cd cross-repo-ops
pip install -e . # optional, for package installpython3 -m cross_repo_opsEl servidor escucha en stdin/stdout mensajes JSON-RPC 2.0.
CROSS_REPO_OPS_CONFIG=/path/to/policy.json python3 -m cross_repo_ops{
"repos": {
"myrepo": {
"root": "/path/to/repo",
"writable": true,
"pushable": false
}
},
"tasks": {
"myrepo": {
"build": {
"command": ["xcodebuild", "-scheme", "MyApp", "build"],
"cwd": "{root}",
"timeout": 180
},
"test": {
"command": ["xcodebuild", "test", "-scheme", "MyApp"],
"cwd": "{root}",
"timeout": 300
}
}
}
}Herramienta | Descripción |
| Lista archivos/directorios con exclusiones de seguridad |
| Búsqueda con ripgrep y salida acotada |
| Lee un fragmento acotado de un archivo de texto no sensible |
| Inspecciona el estado de git |
| Ver diffs sin stagear, stageados y de commits |
| Aplica un parche verificado por contexto (solo repositorios con permiso de escritura) |
| Ejecuta una tarea nombrada aprobada (solo allowlist) |
| Listar/crear/cambiar ramas (repositorios con permiso de escritura para crear/cambiar) |
| Hace stage y commit de archivos explícitos (solo repositorios con permiso de escritura) |
| Push a origin (solo repositorios con permiso de push) |
python3 -m unittest tests.test_security tests.test_adversarial -v32 pruebas que cubren:
Lecturas permitidas y bloqueadas
Rechazo de traversal de rutas, rutas absolutas y escapes por symlink
Bloqueo de lectura/escritura/commit de archivos sensibles
Aplicación de repositorios con permiso de escritura frente a solo lectura
Parche con contexto correcto o desactualizado
Parche dirigido a archivos excluidos
Allowlist de tareas nombradas (éxito, nombre desconocido, intento de inyección de shell)
Timeout de tarea y truncamiento de salida
Git status/diff
Salvaguardas contra inyección en nombres de rama
Salvaguardas de commit (mensaje vacío, archivos sensibles, staging masivo, archivos pre-stageados)
Rechazo de push para repositorios sin permiso de push
Manejo de argumentos faltantes en el servidor
MIT
Apply a bounded, context-checked patch to a file in a writable repository. If old_text is empty and create=true, creates the file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| repo | Yes | ||
| create | No | ||
| context | No | ||
| new_text | Yes | ||
| old_text | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It adds meaningful disclosure beyond the name: the patch is 'bounded' and 'context-checked,' and it explicitly specifies the create-file condition when old_text is empty and create=true. It does not mention return values or failure behavior, but it does convey the most important safety-relevant traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that front-loads the tool's core behavior and adds the key create-condition detail. There is no filler or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, no output schema, and no annotations, yet the description does not explain what happens on context mismatch, whether the change is staged or only in the working tree, or what the tool returns. This leaves an agent with meaningful uncertainty when invoking a mutating patch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only explains old_text and create; repo, path, context, and new_text are left entirely to inference from their names. This is only partial compensation for a 6-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Apply') and resource ('a patch to a file in a writable repository'), and it clarifies a conditional file-creation behavior. It is clearly distinguishable from read-only sibling tools like repo_read and repo_search, though it does not explicitly contrast with git_commit or git_push.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'in a writable repository' implies a prerequisite and suggests this tool is for modifying files, which is useful. However, there is no explicit guidance on when to choose apply_patch over related git siblings, nor any when-not-to-use exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or safely create a branch in a repository.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| action | Yes | ||
| branch_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only says 'safely create' without explaining what safety means, whether creation also switches branches, what side effects occur, or what conditions must hold. It neither confirms nor denies write behavior in detail, so the agent must guess about the operation's actual effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words, making it easy to read. However, it is under-specified for a tool with three parameters and an enum action, so the brevity comes at the cost of missing critical operational detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, an enum action, no annotations, no output schema, and a set of Git sibling tools, the description is not complete enough. It fails to mention the 'switch' behavior, the conditions for branch_name, the safety guarantees implied by 'safely', or what the tool returns, making it hard for an agent to invoke the tool correctly across all cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only loosely implies that 'repo' is a repository and that branch_name relates to creating a branch. It provides no explanation of the 'action' enum values, especially the non-obvious 'switch' value, nor does it clarify when branch_name is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states specific operations ('List or safely create a branch') and a clear resource ('branch in a repository'), which is more specific than the tool name alone. However, it omits the 'switch' action present in the enum, and 'safely' is vague. It does distinguish the tool from the Git siblings, which focus on status, diff, commit, and push.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. The description implies branch listing/creation usage, but it does not clarify when 'switch' should be used, when branch creation is appropriate, or how this relates to sibling tools like git_commit, git_push, or apply_patch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stage and commit files in a writable repository.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| files | Yes | ||
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the tool stages and commits files, which signals a mutating operation, but it does not disclose whether a push happens, what side effects occur on failure, whether the commit is local only, or how the working tree is affected. This is a meaningful gap for a state-changing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. Every word contributes to the basic meaning, and it is far more concise than the schema alone.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is too thin. An agent invoking git_commit needs to understand the commit workflow, whether the operation is local-only, and how the parameters interact; none of that is present. It is minimally recognizable but not sufficient for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate by explaining the three required parameters. It only gives 'files' a role; it does not clarify what 'repo' should contain or what constraints apply to 'message'. The property names are suggestive, but the description adds almost no semantic value beyond them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase, 'Stage and commit files', and names the resource ('a writable repository'), so the tool's core action is clear. It does not explicitly contrast itself with siblings like git_status or git_push, but the commit action is distinct enough for basic identification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as apply_patch, git_status, or git_push. The only contextual hint is 'in a writable repository', which implies a prerequisite but does not explain when a commit is appropriate or when another mutation tool should be chosen instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
View the diff of unstaged or staged changes in a repository.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| repo | Yes | ||
| commit | No | Optional commit ref or range to diff against. | |
| staged | No | ||
| max_chars | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. The verb 'View' implies a read-only operation, but the description does not explicitly state that no changes are made, nor does it mention output size limits, truncation via max_chars, or other behavioral constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler or redundancy. It is front-loaded with the core action and resource, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has five parameters, no output schema, and no annotations, yet the description provides only a minimal overview. It omits critical calling details such as default staging behavior, path/commit semantics, output truncation, and how the diff is returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, and the description does not compensate. It mentions 'unstaged or staged' which maps to the staged boolean, but it does not explain path filtering, the repo parameter, commit ranges, or the max_chars limit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('View') and resource ('diff of unstaged or staged changes in a repository'). It is specific enough to identify this as a git diff tool, though it does not explicitly distinguish itself from siblings like git_status or apply_patch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as git_status, repo_read, or apply_patch. The description implies a review scenario but does not state conditions, exclusions, or preferred use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Push the current or specified branch to origin in a pushable repository.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| branch | No | ||
| remote | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing side effects. It only states 'push ... to origin' without mentioning that remote refs are updated, how non-fast-forward divergence is handled, whether upstream tracking is set, or any failure/error behavior. For a network-mutating operation, this is too thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary elaboration. The only minor filler is 'in a pushable repository', which adds little beyond the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three parameters, one required, and no output schema or annotations, yet the description does not define 'repo' or 'remote'. An agent cannot reliably infer how to target a non-origin remote, what conditions must be true before pushing, or what outcome to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only source of parameter meaning. It clarifies that the current branch can be used and that origin is the default destination, but it never explains the required 'repo' parameter or the optional 'remote' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Push') with a clear resource ('the current or specified branch') and destination ('origin'), which distinguishes it from the sibling git tools like git_commit and git_status. However, 'pushable repository' is vague and the description does not explicitly acknowledge the optional remote parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the verb 'Push' — an agent can infer this is for uploading committed work to a remote. But there is no explicit guidance about when to use this versus git_commit, git_status, or git_diff, and no mention of preconditions such as having local commits or a configured remote.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the current Git repository status.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The word 'Inspect' implies a read-only, non-destructive operation, but the description does not explicitly state safety, side effects, what status information is returned, or any ordering/format details. It adds minimal behavioral context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It front-loads the primary action and resource. While it is minimal, it earns its place and is easy to parse, though it sacrifices detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description should provide more context about what the tool returns and how 'repo' should be supplied. The tool is simple, but the description leaves key operational details unspecified, making it incomplete for an agent that must select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter meaning. The single parameter 'repo' is vaguely self-explanatory, but the description does not clarify whether it should be a path, URL, or repository name. No additional semantic detail is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Inspect the current Git repository status.' This clearly distinguishes it from sibling tools like git_diff, git_branch, and git_commit, none of which are about inspecting overall repository status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool instead of alternatives. It does not mention exclusions, prerequisites, or contrast with sibling tools such as git_diff or git_branch. The only implied usage is when repository status is needed, but this is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a bounded slice of a non-sensitive text file from an allowed repository.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| repo | Yes | ||
| max_lines | No | ||
| start_line | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does communicate important constraints: the read is bounded, limited to text files, and restricted to non-sensitive, allowed repositories. However, it does not explain what happens with sensitive files, disallowed repos, or invalid line ranges.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core action and constraints with no wasted words. It is appropriately concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and four undocumented parameters, the description is incomplete. It omits return format, line-numbering semantics, default slice behavior, and how 'allowed repository' and 'non-sensitive' are determined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It gestures at 'bounded slice,' which hints at start_line and max_lines, but it does not name or explain any parameters, nor does it clarify defaults, indexing, or repo/path formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and identifies a precise resource scope: 'a bounded slice of a non-sensitive text file from an allowed repository.' This clearly distinguishes the tool from siblings like repo_tree, repo_search, and git_diff, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus its siblings. It implies a use case for reading file content, but does not mention alternatives like repo_search for finding content or repo_tree for exploring structure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search an allowed repository using ripgrep with bounded output and safety exclusions.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| repo | Yes | ||
| pattern | Yes | ||
| file_glob | No | ||
| max_results | No | ||
| word_regexp | No | ||
| fixed_string | No | ||
| context_lines | No | ||
| case_sensitive | No | ||
| files_with_matches | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does reveal that the tool is read-only in nature ('search'), uses ripgrep, caps output ('bounded output'), and applies some form of filtering ('safety exclusions'). However, 'allowed repository' and 'safety exclusions' are undefined, and no side effects or permission requirements are discussed, which is a meaningful gap for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. It efficiently communicates the core action and resource, but the vague terms 'allowed' and 'safety exclusions' could have been clarified without much extra length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 parameters, no annotations, no output schema, and zero schema description coverage, this description is far from complete. It omits parameter semantics, output format, and the concrete meaning of safety exclusions, leaving an agent unable to configure the tool correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for 10 parameters but does not. It only hints at 'bounded output' (relating to max_results) and 'safety exclusions' (possibly path/file_glob), leaving the other parameters like pattern, word_regexp, fixed_string, context_lines, and case_sensitive unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('search'), a resource ('allowed repository'), the underlying mechanism ('ripgrep'), and distinctive constraints ('bounded output and safety exclusions'). This clearly distinguishes it from siblings like repo_tree (structure listing) and repo_read (file contents).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. There are no usage scenarios, prerequisites, or exclusions mentioned. The only hint is the verb 'search', which weakly implies its role among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and directories in an allowed repository with safety exclusions.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional repo-relative directory or file path. | |
| repo | Yes | Allowed repository name. | |
| max_entries | No | Maximum entries to return, capped at 500. | |
| include_hidden | No | Whether to include hidden files. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the behavioral burden. It mentions 'safety exclusions' but does not specify what those exclusions are, whether results are recursive, how hidden files are handled by default, or what the return format looks like. For a listing tool with no output schema, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no redundancy. It earns its place by stating the core action and a key constraint, though the vagueness of 'safety exclusions' means some brevity is achieved at the cost of clarity. Still, this is concise rather than incomplete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description is too minimal to fully support correct invocation. It does not explain what 'safety exclusions' contains, whether the result is a nested tree or flat list, or how this relates to the sibling tools. Four parameters and one required field deserve more context for reliable selection and use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have schema descriptions (100% coverage), so the baseline is 3. The tool description does not add parameter-specific meaning; 'safety exclusions' may relate to include_hidden or max_entries, but that connection is not made explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'List files and directories in an allowed repository'. It is distinct from sibling tools like repo_read (file contents) and repo_search (search), though it does not explicitly name alternatives. The phrase 'safety exclusions' hints at a scope but is vague, keeping this from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus repo_read, repo_search, or git_status. The 'allowed repository' phrase implies a precondition but not a selection criterion. There are no exclusions or references to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an approved named task for a repository. No arbitrary shell commands are accepted.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| repo | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully discloses that only approved named tasks are run and arbitrary shell commands are rejected, but it does not describe side effects on the repository, approval requirements, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler, front-loading the core action and then adding a key constraint. It is efficiently written, though its brevity contributes to the lack of contextual detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, no annotations, and two required parameters, an agent still does not know what tasks are available, what running a task does to the repository, or what response to expect. The description covers a precondition but not the effects or results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only source of parameter meaning. It implies 'name' is a task identifier and 'repo' is the target repository, but it never defines valid task names, repo formats, or defaults, leaving significant ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Run' and the resource 'an approved named task for a repository,' and explicitly distinguishes itself from arbitrary command execution. It is specific enough to separate it from the repo/git siblings, though 'approved task' is not fully defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: call this when you need to execute a pre-approved named task. The statement that arbitrary shell commands are not accepted provides a negative boundary, but no explicit alternatives or when-to-use versus when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0apply_patchgit_branchgit_commitgit_diffgit_pushgit_statusrepo_readrepo_searchrepo_treerun_taskScored across 10 tools
Each tool maps cleanly to a distinct action: repo_* covers content browsing/search, git_* covers repository state operations, and apply_patch/run_task cover modifications. Adjacent tools like git_status and git_diff are clearly separated by purpose. No two tools appear to do the same thing.
Most tools follow a clear domain-prefix pattern: repo_* for content operations and git_* for VCS operations. The exceptions are apply_patch and run_task, which use bare verb_noun names but remain readable and consistent with the overall snake_case style.
Ten tools is an ideal size for this scope; each tool covers a distinct operation without redundancy. The set feels intentionally scoped rather than padded.
The read/search → patch → branch → commit → push workflow provides a complete edit-and-publish lifecycle. Minor gaps include no repository enumeration, no git pull/fetch, and no way to list approved run_task tasks, but these do not block the primary workflow.
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Remote MCP for Android CLI agent build gate, structured receipts, audit logs, and reviewer-ready evi
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
