Add agent-friendly tool validation and execution contracts

[dannon]

Summary

Adds a tool contract system for agent-friendly tool validation and execution:

• tool_contract.py — builds structured contracts describing tool inputs/outputs with validation, and provides validate_payload_against_contract for pre-flight parameter checking
• build_agent_hints — generates agent-oriented guidance for tool usage
• Comprehensive test suite in test_tool_validation.py

Authored by @paulocilasjr.

Test plan

• make lint passes
• make test passes
• Verify tool contracts generate correct schemas for representative Galaxy tools

[dannon]

Thanks for this, @paulocilasjr — the contract/validation approach is solid and the test coverage is great.

One thing worth thinking about for the next iteration: Galaxy now has formal JSON Schema endpoints for tool inputs. The Tool Shed already serves these live:

GET /api/tools/{owner}~{repo}~{tool_id}/versions/{version}/parameter_request_schema

For example, FastQC's schema:

https://toolshed.g2.bx.psu.edu/api/tools/devteam~fastqc~fastqc/versions/0.74+galaxy1/parameter_request_schema

These return proper JSON Schema (draft 2020-12) generated from Pydantic models. They handle the hard stuff natively:

• Conditionals become oneOf discriminated unions — each <when> case is a separate sub-schema with the selector constrained to a const value, plus an __absent__ branch for the default
• Repeats become array types with minItems/maxItems
• Sections become nested objects
• Selects use const/anyOf for static options
• Data inputs use discriminated unions based on src (hda, ldda, url, etc.) with typed ID fields

The same endpoints also exist on the Galaxy server API (/api/tools/{tool_id}/parameter_request_schema) but only on the dev branch — they'll ship in the next Galaxy release (probably 26.0). Once that lands, you'd get schemas for tools as installed on the target instance, including dynamic options.

What this means for tool_contract.py: the build_tool_contract / _walk_tool_inputs code (~175 lines) that parses the legacy show_tool() response to reconstruct the input structure could eventually be replaced by fetching the formal schema. That'd be more robust since you wouldn't be maintaining a parallel parser for Galaxy's input model.

The validation layer (validate_payload_against_contract) is the part that stays valuable regardless — the conditional selector enforcement, data column index checking, JSON escaping warnings, dataset preflight checks, and the iterative tools.build() resolution are all Galaxy-agent-specific concerns that no generic JSON Schema validator would handle.

I'm sketching out a plan to build on this work using the formal schemas. The rough shape:

1. Schema fetching layer — try the Galaxy server's /api/tools/{id}/parameter_request_schema first (once 26.0 ships), fall back to the Tool Shed endpoint for toolshed-installed tools. Cache aggressively. Built-in tools (upload1, cat1, etc.) would still need the legacy path since they don't live in the Tool Shed.

2. Swap the contract builder — replace build_tool_contract / _walk_tool_inputs with the fetched JSON Schema. Use jsonschema library for standard validation (required fields, unknown keys, conditional case matching via oneOf, select values via const). This eliminates the custom input parser.

3. Keep your Galaxy-specific checks on top — the dataset preflight, iterative tools.build() resolution, data column 1-indexing, JSON escaping warnings all stay. These are the things that make this useful for agents beyond what a generic validator provides.

4. Expose the schema directly to MCP clients — JSON Schema is a format LLMs already understand natively. Instead of translating Galaxy's inputs into a custom contract format, we can hand the schema to the agent directly and let it construct valid payloads from the spec.

No need to block this PR on any of that — your work here gives us the validation infrastructure and dataset preflight layer that we'd build on regardless of schema source. Merging this and iterating on top makes the most sense.

[paulocilasjr]

Awesome.