Foundry
Home Schema

Galaxy tool discovery recommendation

JSON Schema for Tool Shed discovery hit, weak, and miss recommendations.

draft schematarget/galaxy
Revised
2026-05-04
Rev
1
Molds
schema galaxy-tool-discovery @galaxy-foundry/foundry @ 0.0.0 upstream ↗

Galaxy Tool Discovery Recommendation

Structured recommendation emitted by the discover-shed-tool Mold after searching the Galaxy Tool Shed and resolving any selected candidate to a pinnable Tool Shed version and changeset revision.

3 definitions. Anchor links per definition (e.g. #has_text_model) are stable.

DiscoveryRecommendation

DiscoveryRecommendation

Top-level output from discover-shed-tool. A hit or weak result carries a selected candidate; a miss carries null candidate plus fallthrough rationale.

field type req description
alternates → ToolCandidate[] ✓ Runner-up candidates worth surfacing to the user or harness. Empty when no plausible alternates were found.
candidate → ToolCandidate | null ✓ Selected candidate for hit/weak results. Null for miss.
rationale string ✓ Short explanation of why this status and candidate were selected, including ambiguity or fallthrough reasoning.
status string ✓ Recommendation class. hit means proceed with the selected Tool Shed pin; weak means candidate exists but needs confirmation or may fall through; miss means no usable wrapper was found.
warnings → Warning[] ✓ Advisory issues that do not invalidate the recommendation but affect confidence or downstream binding.

ToolCandidate

ToolCandidate

One Tool Shed candidate plus the version and changeset pin needed by downstream caching and gxformat2 authoring.

field type req description
changeset_revision string ✓ Selected Tool Shed Mercurial changeset revision for reproducible gxformat2 tool_shed_repository pinning.
match_fields string[] ✓ Candidate fields or hints that matched the query. Preserves the older sketch's name/description-style evidence separately from matched_terms.
matched_terms string[] ✓ Query terms or exact hints that matched this candidate. Empty only when the candidate came from a non-lexical hint.
owner string ✓ Tool Shed repository owner, e.g. devteam or iuc.
rationale string ✓ Candidate-specific explanation, especially for alternates and weak recommendations.
repo string ✓ Tool Shed repository name containing the wrapper. Maps from gxwf search's repoName field.
score number ✓ Search score or cast-skill confidence score used to rank this candidate. Higher is better.
tool_id string ✓ Galaxy XML tool id inside the repository.
tool_shed_url string ✓ Tool Shed base URL searched, normally https://toolshed.g2.bx.psu.edu.
trs_tool_id string ✓ Tool Shed TRS-style id: <owner>~<repo>~<tool_id>. Used for gxwf tool-versions and tool-revisions.
version string ✓ Selected Galaxy XML tool version, usually the newest installable version unless the caller requested a specific version.

Warning

Warning

Advisory confidence issue surfaced by discover-shed-tool.

field type req description
code string ✓ Machine-stable warning category.
message string ✓ Human-readable warning detail.

This page is auto-rendered from the JSON Schema authored in this repo. Each $def becomes a section below with a stable anchor ID — research notes and Mold bodies can deep-link individual shapes via galaxy-tool-discovery#ToolCandidate.

Source-of-truth chain:

  1. packages/foundry/src/schemas/galaxy-tool-discovery/galaxy-tool-discovery.schema.json — the canonical JSON, hand-edited as part of the Mold/cast loop around discover-shed-tool. Mold frontmatter cites it via galaxy-tool-discovery wiki-links; cast imports the galaxyToolDiscoverySchema runtime export and serializes it into cast bundles.
  2. packages/foundry/scripts/sync-schema.mjs runs at prebuild, regenerating the typed galaxy-tool-discovery.schema.generated.ts const wrapper from the canonical JSON.
  3. Published as part of @galaxy-foundry/foundry (orphan schema bundled in the unified CLI). Site rendering imports the schema directly from this package via site/src/lib/schema-registry.ts; the published CLI also ships foundry validate-galaxy-tool-discovery for cast skills and downstream consumers.

At runtime in cast skills: validation should happen through the CLI command:

foundry validate-galaxy-tool-discovery recommendation.json

Library validation exists for TypeScript consumers, but generated skills should prefer command-shaped validation so failures are easy to reproduce outside the agent runtime.

Why recommendation-shaped

discover-shed-tool is not just a thin gxwf tool-search wrapper. It searches, resolves candidate versions, resolves changeset revisions, ranks alternates, and decides whether the harness should proceed, ask for confirmation, or fall through to author-galaxy-tool-wrapper. The schema therefore models the recommendation boundary rather than any one upstream CLI response.

The deterministic primitive outputs stay upstream in @galaxy-tool-util/*:

  • gxwf tool-search emits Tool Shed hits.
  • gxwf tool-versions resolves TRS versions.
  • gxwf tool-revisions resolves installable changeset revisions.
  • galaxy-tool-cache add materializes the selected wrapper for summarize-galaxy-tool.

The Foundry-owned recommendation shape adds the LLM/harness semantics those commands intentionally do not own: hit, weak, miss, alternates, warnings, and rationale.

Field naming

The schema uses Foundry’s JSON contract style: snake_case fields such as tool_shed_url, tool_id, trs_tool_id, and changeset_revision. These map cleanly from the current TypeScript CLI surfaces (repoName, toolId, trsToolId, changesetRevision) without making the Foundry schema inherit TS implementation casing.

repo means the Tool Shed repository name. This intentionally differs from repoName in gxwf JSON because downstream Molds should see a stable Foundry contract, not a direct CLI type dump.

Cast-time role

Per docs/COMPILATION_PIPELINE.md’s per-kind dispatch, this schema is referenced by discover-shed-tool via output_artifacts[].schema and copied verbatim into the cast bundle’s references/schemas/. The cast skill validates its emitted recommendation with validate-galaxy-tool-discovery before returning; downstream phases bind to this object and would produce worse errors later.

The same object feeds several consumers:

What is intentionally not modeled

  • Cache keys. The discovery object carries enough information to run galaxy-tool-cache add, but it does not freeze the cache’s internal key format.
  • ParsedTool content. Full wrapper structure belongs to summarize-galaxy-tool after cache population, not to discovery.
  • Galaxy-instance search. Installed-tool discovery through a configured Galaxy server is a future sibling path, not part of this Tool Shed schema.
  • Automatic top-1 fetch. A future gxwf tool-fetch convenience command could reduce shell steps, but it would not replace this recommendation schema because it does not model weak, miss, fallthrough context, or alternates.

Incoming References (2)

  • Validate Galaxy Tool Discoveryrelated note— AJV gate for discover-shed-tool recommendation documents.
  • discover-shed-toolschema of artifact output— Search the Tool Shed for an existing wrapper, drill from hit to a pinnable changeset, classify candidates, and recommend or fall through.