devtu-fix-tool

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fix ToolUniverse Tools

修复ToolUniverse工具

Diagnose and fix failing ToolUniverse tools through systematic error identification, targeted fixes, and validation.

通过系统化的错误定位、针对性修复和验证流程，诊断并修复出现问题的ToolUniverse工具。

Instructions

操作步骤

When fixing a failing tool:

Run targeted test to identify error:

bash

python scripts/test_new_tools.py <tool-pattern> -v

Verify API is correct - search online for official API documentation to confirm endpoints, parameters, and patterns are correct
Identify error type (see Error Types section)
Apply appropriate fix based on error pattern
Regenerate tools if you modified JSON configs or tool classes:

bash

python -m tooluniverse.generate_tools

Check and update unit tests if they exist in
```
tests/unit/
```
:

bash

ls tests/unit/test_<tool-name>_tool.py

Verify fix by re-running both integration and unit tests
Provide fix summary with problem, root cause, solution, and test results

修复故障工具时，请遵循以下步骤：

运行针对性测试以定位错误：

bash

python scripts/test_new_tools.py <tool-pattern> -v

验证API正确性 - 查阅官方API文档，确认接口地址、参数和调用方式是否正确
确定错误类型（参考「错误类型」章节）
根据错误类型应用对应修复方案
若修改了JSON配置或工具类，重新生成工具：

bash

python -m tooluniverse.generate_tools

检查并更新单元测试（如果单元测试文件存在于
```
tests/unit/
```
目录中）：

bash

ls tests/unit/test_<tool-name>_tool.py

重新运行集成测试和单元测试，验证修复效果
提供修复总结，包含问题描述、根本原因、解决方案和测试结果

Where to Fix

修复位置参考

Issue Type	File to Modify
Binary response	`src/tooluniverse/_tool.py` + `src/tooluniverse/data/_tools.json`
Schema mismatch	`src/tooluniverse/data/*_tools.json` (return_schema)
Missing data wrapper	`src/tooluniverse/*_tool.py` (operation methods)
Endpoint URL	`src/tooluniverse/data/*_tools.json` (endpoint field)
Invalid test example	`src/tooluniverse/data/*_tools.json` (test_examples)
Unit test updates	`tests/unit/test_*_tool.py` (if exists)
API key as parameter	`src/tooluniverse/data/_tools.json` (remove param) + `_tool.py` (use env var)
Tool not loading (optional key)	`src/tooluniverse/data/*_tools.json` (use `optional_api_keys` not `required_api_keys` )

问题类型	需要修改的文件
二进制响应	`src/tooluniverse/_tool.py` + `src/tooluniverse/data/_tools.json`
Schema不匹配	`src/tooluniverse/data/*_tools.json` （ `return_schema` 字段）
缺少数据包装层	`src/tooluniverse/*_tool.py` （操作方法）
接口地址错误	`src/tooluniverse/data/*_tools.json` （ `endpoint` 字段）
测试示例无效	`src/tooluniverse/data/*_tools.json` （ `test_examples` 字段）
单元测试更新	`tests/unit/test_*_tool.py` （如果存在）
API密钥作为参数传递	`src/tooluniverse/data/_tools.json` （移除对应参数） + `_tool.py` （改用环境变量）
工具无法加载（可选密钥）	`src/tooluniverse/data/*_tools.json` （使用 `optional_api_keys` 而非 `required_api_keys` ）

Error Types

错误类型

1. JSON Parsing Errors

1. JSON解析错误

Symptom:

Expecting value: line 1 column 1 (char 0)

Cause: Tool expects JSON but receives binary data (images, PDFs, files)

Fix: Check Content-Type header. For binary responses, return a description string instead of parsing JSON. Update

return_schema

{"type": "string"}

症状：

Expecting value: line 1 column 1 (char 0)

原因：工具预期接收JSON格式数据，但实际收到二进制数据（如图片、PDF、文件）

修复方案：检查响应头的Content-Type字段。对于二进制响应，返回描述性字符串而非解析JSON。将

return_schema

更新为

{"type": "string"}

。

2. Schema Validation Errors

2. Schema验证错误

Symptom:

Schema Mismatch: At root: ... is not of type 'object'

Data: None

Cause: Missing

data

field wrapper OR wrong schema type

Fix depends on the error:

If
```
Data: None
```
→ Add
```
data
```
wrapper to ALL operation methods (see Multi-Operation Pattern below)

If type mismatch → Update

return_schema

in JSON config:

Data is string:
```
{"type": "string"}
```
Data is array:
```
{"type": "array", "items": {...}}
```
Data is object:
```
{"type": "object", "properties": {...}}
```

Key concept: Schema validates the

data

field content, NOT the full response.

症状：

Schema Mismatch: At root: ... is not of type 'object'

或

Data: None

原因：缺少

data

字段包装层，或Schema类型错误

根据具体错误修复：

若出现
```
Data: None
```
→ 为所有操作方法添加
```
data
```
包装层（参考下文「多操作工具模式」）
若类型不匹配 → 更新JSON配置中的
```
return_schema
```
：
- 数据为字符串：
```
{"type": "string"}
```
- 数据为数组：
```
{"type": "array", "items": {...}}
```
- 数据为对象：
```
{"type": "object", "properties": {...}}
```

核心概念：Schema验证的是

data

字段的内容，而非完整响应体。

3. Nullable Field Errors

3. 可空字段错误

Symptom:

Schema Mismatch: At N->fieldName: None is not of type 'integer'

Cause: API returns

None

null

for optional fields

Fix: Allow nullable types in JSON config using

{"type": ["<base_type>", "null"]}

. Use for optional fields, not required identifiers.

症状：

Schema Mismatch: At N->fieldName: None is not of type 'integer'

原因：API为可选字段返回

None

null

值

修复方案：在JSON配置中使用

{"type": ["<base_type>", "null"]}

允许字段为可空类型。仅适用于可选字段，不适用于必填标识符。

4. Mutually Exclusive Parameter Errors

4. 互斥参数错误

Symptom:

Parameter validation failed for 'param_name': None is not of type 'integer'

when passing a different parameter

Cause: Tool accepts EITHER paramA OR paramB (mutually exclusive), but both are defined with fixed types. When only one is provided, validation fails because the other is

None

Example:

json

{
  "neuron_id": {"type": "integer"},      // ❌ Fails when neuron_name is used
  "neuron_name": {"type": "string"}      // ❌ Fails when neuron_id is used
}

Fix: Make mutually exclusive parameters nullable:

json

{
  "neuron_id": {"type": ["integer", "null"]},      // ✅ Allows None
  "neuron_name": {"type": ["string", "null"]}      // ✅ Allows None
}

Common patterns:

```
id
```
OR
```
name
```
parameters (get by ID or by name)
```
acronym
```
OR
```
name
```
parameters (search by symbol or full name)
Optional filter parameters that may not be provided

Important: Also make truly optional parameters (like

filter_field

filter_value

) nullable even if not mutually exclusive.

症状：当传递某一参数时，出现

Parameter validation failed for 'param_name': None is not of type 'integer'

原因：工具支持参数A或参数B（二者互斥），但两者均被定义为固定类型。当仅提供其中一个参数时，另一个参数为

None

会导致验证失败。

示例：

json

{
  "neuron_id": {"type": "integer"},      // ❌ 使用neuron_name时会失败
  "neuron_name": {"type": "string"}      // ❌ 使用neuron_id时会失败
}

修复方案：将互斥参数设置为可空：

json

{
  "neuron_id": {"type": ["integer", "null"]},      // ✅ 允许为None
  "neuron_name": {"type": ["string", "null"]}      // ✅ 允许为None
}

常见场景：

```
id
```
或
```
name
```
参数（通过ID或名称获取资源）
```
acronym
```
或
```
name
```
参数（通过符号或全名搜索）
可能不提供的可选过滤参数

注意：即使不是互斥参数，真正的可选参数（如

filter_field

、

filter_value

）也应设置为可空。

5. Mixed Type Field Errors

5. 混合类型字段错误

Symptom:

Schema Mismatch: At N->field: {object} is not of type 'string', 'null'

Cause: Field returns different structures depending on context

Fix: Use

oneOf

in JSON config for fields with multiple distinct schemas. Different from nullable (

{"type": ["string", "null"]}

) which is same base type + null.

症状：

Schema Mismatch: At N->field: {object} is not of type 'string', 'null'

原因：字段会根据上下文返回不同结构的数据

修复方案：对于具有多种不同Schema的字段，在JSON配置中使用

oneOf

。这与可空类型（

{"type": ["string", "null"]}

，同一基础类型+空值）不同。

6. Invalid Test Examples

6. 无效测试示例错误

Symptom:

404 ERROR - Not found

400 Bad Request

Cause: Test example uses invalid/outdated IDs

Fix: Discover valid examples using the List → Get or Search → Details patterns below.

症状：

404 ERROR - Not found

或

400 Bad Request

原因：测试示例使用了无效/过时的ID

修复方案：通过以下方式获取有效示例：列表→详情或搜索→详情（参考下文模式）。

7. API Parameter Errors

7. API参数错误

Symptom:

400 Bad Request

or parameter validation errors

Fix: Update parameter schema in JSON config with correct types, required fields, and enums.

症状：

400 Bad Request

或参数验证错误

修复方案：更新JSON配置中的参数Schema，确保类型、必填字段和枚举值正确。

8. API Key Configuration Errors

8. API密钥配置错误

Symptom: Tool not loading when API key is optional, or

api_key

parameter causing confusion

Cause: Using

required_api_keys

for keys that should be optional, or exposing API key as tool parameter

Key differences:

```
required_api_keys
```
: Tool is skipped if keys are missing
```
optional_api_keys
```
: Tool loads and works without keys (with reduced performance)

Fix: Use

optional_api_keys

in JSON config for APIs that work anonymously but have better rate limits with keys. Read API key from environment only (

os.environ.get()

), never as a tool parameter.

症状：当API密钥为可选时工具无法加载，或

api_key

参数造成混淆

原因：将应为可选的密钥标记为

required_api_keys

，或将API密钥暴露为工具参数

核心区别：

```
required_api_keys
```
：若缺少密钥，工具会被跳过加载
```
optional_api_keys
```
：即使缺少密钥，工具仍会加载并正常工作（功能可能受限）

修复方案：对于支持匿名访问但提供密钥可获得更高调用限额的API，在JSON配置中使用

optional_api_keys

。仅从环境变量读取API密钥（

os.environ.get()

），绝不要将其作为工具参数。

9. API Endpoint Pattern Errors

9. API接口模式错误

Symptom:

for valid resources, or unexpected results

Fix: Verify official API docs - check if values belong in URL path vs query parameters.

症状：有效资源返回

，或结果不符合预期

修复方案：查阅官方API文档，确认参数应放在URL路径中还是查询参数中。

10. Transient API Failures

10. 临时性API故障

Symptom: Tests fail intermittently with timeout/connection/5xx errors

Fix: Use

pytest.skip()

for transient errors in unit tests - don't fail on external API outages.

症状：测试间歇性失败，出现超时/连接错误/5xx错误

修复方案：在单元测试中对临时性错误使用

pytest.skip()

，不要因外部API故障导致测试失败。

Common Fix Patterns

常见修复模式

Schema Validation Pattern

Schema验证模式

Schema validates the

data

field content, not the full response. Match

return_schema

type to what's inside

data

(array, object, or string).

Schema验证的是

data

字段的内容，而非完整响应体。确保

return_schema

的类型与

data

字段内的数据类型匹配（数组、对象或字符串）。

Multi-Operation Tool Pattern

多操作工具模式

Every internal method must return

{"status": "...", "data": {...}}

. Don't use alternative field names at top level.

所有内部方法必须返回

{"status": "...", "data": {...}}

格式的数据。不要在顶层使用其他字段名。

Finding Valid Test Examples

获取有效测试示例

When test examples fail with 400/404, discover valid IDs by:

List → Get: Call a list endpoint first, extract ID from results
Search → Details: Search for a known entity, use returned ID
Iterate Versions: Try different dataset versions if supported

当测试示例返回400/404错误时，可通过以下方式获取有效ID：

列表→详情：先调用列表接口，从结果中提取ID
搜索→详情：搜索已知实体，使用返回的ID
尝试不同版本：若支持，尝试不同的数据集版本

Unit Test Management

单元测试管理

Check for Unit Tests

检查单元测试是否存在

After fixing a tool, check if unit tests exist:

bash

ls tests/unit/test_<tool-name>_tool.py

修复工具后，检查是否存在单元测试：

bash

ls tests/unit/test_<tool-name>_tool.py

When to Update Unit Tests

何时更新单元测试

Update unit tests when you:

Change return structure: Update assertions checking
```
result["data"]
```
structure
Add/modify operations: Add test cases for new operations
Change error handling: Update error assertions
Modify required parameters: Update parameter validation tests
Fix schema issues: Ensure tests validate correct data structure
Add binary handling: Add tests for binary responses

在以下场景下更新单元测试：

返回结构变更：更新检查
```
result["data"]
```
结构的断言
新增/修改操作：为新操作添加测试用例
错误处理变更：更新错误断言
必填参数修改：更新参数验证测试
Schema问题修复：确保测试验证正确的数据结构
新增二进制处理：添加二进制响应的测试用例

Running Unit Tests

运行单元测试

bash

undefined

bash

undefined

Run specific tool tests

运行特定工具的测试

pytest tests/unit/test_<tool-name>_tool.py -v

Run all unit tests

运行所有单元测试

pytest tests/unit/ -v

undefined

pytest tests/unit/ -v

undefined

Unit Test Checklist

单元测试检查清单

Check if
```
tests/unit/test_<tool-name>_tool.py
```
exists
Run unit tests before and after fix
Update assertions if data structure changed
Ensure both direct and interface tests pass

For detailed unit test patterns and examples, see unit-tests-reference.md.

检查是否存在
```
tests/unit/test_<tool-name>_tool.py
```
文件
修复前后均运行单元测试
若数据结构变更，更新断言
确保直接调用和接口调用测试均通过

如需详细的单元测试模式和示例，请参考unit-tests-reference.md。

Verification

验证流程

Run Integration Tests

运行集成测试

bash

python scripts/test_new_tools.py <pattern> -v

bash

python scripts/test_new_tools.py <pattern> -v

Run Unit Tests (if exist)

运行单元测试（如果存在）

bash

pytest tests/unit/test_<tool-name>_tool.py -v

bash

pytest tests/unit/test_<tool-name>_tool.py -v

Regenerate Tools

重新生成工具

After modifying JSON configs or tool classes:

bash

python -m tooluniverse.generate_tools

Regenerate after:

Changing
```
src/tooluniverse/data/*_tools.json
```
files
Modifying tool class implementations

Not needed for test script changes.

修改JSON配置或工具类后：

bash

python -m tooluniverse.generate_tools

在以下场景后需要重新生成：

修改了
```
src/tooluniverse/data/*_tools.json
```
文件
修改了工具类实现

修改测试脚本无需重新生成工具。

Output Format

输出格式

After fixing, provide this summary:

Problem: [Brief description]

Root Cause: [Why it failed]

Solution: [What was changed]

Changes Made:

File 1: [Description]
File 2: [Description]
File 3 (if applicable): [Unit test updates]

Integration Test Results:

Before: X tests, Y passed (Z%), N failed, M schema invalid
After: X tests, X passed (100.0%), 0 failed, 0 schema invalid

Unit Test Results (if applicable):

Before: X tests, Y passed, Z failed
After: X tests, X passed, 0 failed

修复完成后，请提供以下总结：

问题：[简要描述]

根本原因：[失败原因]

解决方案：[修改内容]

已做变更：

文件1：[描述]
文件2：[描述]
文件3（如有）：[单元测试更新内容]

集成测试结果：

修复前：X个测试，Y个通过（Z%），N个失败，M个Schema无效
修复后：X个测试，X个通过（100.0%），0个失败，0个Schema无效

单元测试结果（如有）：

修复前：X个测试，Y个通过，Z个失败
修复后：X个测试，X个通过，0个失败

Testing Best Practices

测试最佳实践

Verify Parameter Names Before Testing

测试前验证参数名称

CRITICAL: Always read the tool's JSON config or generated wrapper to get the correct parameter names. Don't assume parameter names.

Example of incorrect testing:

python

undefined

关键注意事项：务必查看工具的JSON配置或生成的封装代码，获取正确的参数名称，不要主观臆断。

错误测试示例：

python

undefined

❌ WRONG - assumed parameter name

❌ 错误 - 主观臆断参数名称

AllenBrain_search_genes(query='Gad1') # Fails: unexpected keyword 'query'


**Correct approach**:
```python

AllenBrain_search_genes(query='Gad1') # 失败：出现意外关键字'query'


**正确做法**：
```python

✅ RIGHT - checked config first

✅ 正确 - 先查看配置

Config shows parameters: gene_acronym, gene_name

配置显示参数为：gene_acronym, gene_name

AllenBrain_search_genes(gene_acronym='Gad1') # Works!


**How to find correct parameter names**:
1. Read the JSON config: `src/tooluniverse/data/*_tools.json`
2. Check the generated wrapper: `src/tooluniverse/tools/<ToolName>.py`
3. Look at test_examples in the JSON config

AllenBrain_search_genes(gene_acronym='Gad1') # 正常运行!


**如何获取正确参数名称**：
1. 查看JSON配置：`src/tooluniverse/data/*_tools.json`
2. 查看生成的封装代码：`src/tooluniverse/tools/<ToolName>.py`
3. 查看JSON配置中的test_examples字段

Systematic Testing Approach

系统化测试方法

When testing multiple tools:

Sample first: Test 1-2 tools per API to identify patterns
Categorize errors: Group by error type (param validation, API errors, data structure)
Fix systematically: Fix all tools with same issue type together
Regenerate once: Run
```
python -m tooluniverse.generate_tools
```
after all JSON changes
Verify all: Test all fixed tools comprehensively

测试多个工具时：

先抽样测试：每个API测试1-2个工具，定位共性问题
错误分类：按错误类型分组（参数验证、API错误、数据结构）
批量修复：一次性修复所有同类型问题的工具
统一重新生成：完成所有JSON修改后，运行
```
python -m tooluniverse.generate_tools
```
全面验证：对所有修复后的工具进行完整测试

Understanding Data Structure

理解数据结构

Tools can return different data structures:

Object:
```
{"data": {"id": 1, "name": "..."}}
```
- single result
Array:
```
{"data": [{"id": 1}, {"id": 2}]}
```
- multiple results
String:
```
{"data": "description text"}
```
- text response

Test accordingly:

python

undefined

工具可能返回不同的数据结构：

对象：
```
{"data": {"id": 1, "name": "..."}}
```
- 单个结果
数组：
```
{"data": [{"id": 1}, {"id": 2}]}
```
- 多个结果
字符串：
```
{"data": "description text"}
```
- 文本响应

对应测试方式：

python

undefined

For object data

针对对象数据

result = tool() data = result.get('data', {}) value = data.get('field_name') # ✅

For array data

针对数组数据

result = tool() items = result.get('data', []) count = len(items) # ✅ first = items[0] if items else {} # ✅

undefined

result = tool() items = result.get('data', []) count = len(items) # ✅ first = items[0] if items else {} # ✅

undefined

Common Pitfalls

常见误区

Schema validates
data
field, not full response
All methods need
{"status": "...", "data": {...}}
wrapper
JSON config changes require regeneration
Use
optional_api_keys
for APIs that work without keys
Check official API docs for correct endpoint patterns
Unit tests should skip on transient API failures, not fail
Mutually exclusive parameters MUST be nullable - most common new tool issue
Verify parameter names from configs - don't assume or guess
Test with correct data structure expectations - list vs dict vs string

Schema验证的是
data
字段，而非完整响应体
**所有方法必须返回
```
{"status": "...", "data": {...}}
```
**包装结构
修改JSON配置后必须重新生成工具
对支持匿名访问的API使用
optional_api_keys
查阅官方API文档确认正确的接口模式
单元测试应跳过临时性API故障，不要标记为失败
互斥参数必须设置为可空 - 这是新工具最常见的问题
从配置中验证参数名称 - 不要主观臆断
根据预期数据结构进行测试 - 区分列表、字典和字符串

Debugging

调试技巧

Inspect API response: Check status code, Content-Type header, and body preview
Check tool config: Load ToolUniverse and inspect the tool's configuration
Add debug prints: Log URL, params, status, and Content-Type in the run method

检查API响应：查看状态码、Content-Type响应头和响应体预览
检查工具配置：加载ToolUniverse并查看工具的配置信息
添加调试打印：在运行方法中记录URL、参数、状态码和Content-Type

Quick Reference

速查指南

Task	Command
Run integration tests	`python scripts/test_new_tools.py <pattern> -v`
Run unit tests	`pytest tests/unit/test_<tool-name>_tool.py -v`
Check if unit tests exist	`ls tests/unit/test_<tool-name>_tool.py`
Regenerate tools	`python -m tooluniverse.generate_tools`
Check status	`git status --short \| grep -E "(data\|tools\|.*_tool.py\|tests/unit)"`

Error Type	Fix Location
JSON parse error	`src/tooluniverse/*_tool.py` run() method
Schema mismatch	`src/tooluniverse/data/*_tools.json` return_schema
404 errors	`src/tooluniverse/data/*_tools.json` test_examples or endpoint
Parameter errors	`src/tooluniverse/data/*_tools.json` parameter schema
Unit test failures	`tests/unit/test_*_tool.py` assertions
Tool skipped (optional key)	`src/tooluniverse/data/*_tools.json` use `optional_api_keys`
API key as parameter	Remove from JSON params, use `os.environ.get()` in Python

任务	命令
运行集成测试	`python scripts/test_new_tools.py <pattern> -v`
运行单元测试	`pytest tests/unit/test_<tool-name>_tool.py -v`
检查单元测试是否存在	`ls tests/unit/test_<tool-name>_tool.py`
重新生成工具	`python -m tooluniverse.generate_tools`
检查状态	`git status --short \| grep -E "(data\|tools\|.*_tool.py\|tests/unit)"`

错误类型	修复位置
JSON解析错误	`src/tooluniverse/*_tool.py` 的run()方法
Schema不匹配	`src/tooluniverse/data/*_tools.json` 的return_schema字段
404错误	`src/tooluniverse/data/*_tools.json` 的test_examples或endpoint字段
参数错误	`src/tooluniverse/data/*_tools.json` 的参数Schema
单元测试失败	`tests/unit/test_*_tool.py` 的断言
工具因可选密钥被跳过	`src/tooluniverse/data/*_tools.json` 改用 `optional_api_keys`
API密钥作为参数传递	从JSON参数中移除，在Python代码中使用 `os.environ.get()`