catalog_list vs tools_list: finding HTTP-only Sume features

An agent that only reads tools_list can wrongly conclude that Sume has no way to do something. The hosted docs say catalog_list can still show HTTP capabilities that do not have an MCP tool (read 2026-10-05 in the repo docs). The quickstart describes it as listing the public API capabilities, which is more than the MCP tools. Read both lists, then pick the surface.

Two lists, two questions

tools_list answers what this session can call right now. It is scope-filtered, so an OAuth mcp:read session sees only read tools. catalog_list answers what the public API can do at all. A capability can be present in the catalog and absent from the tool list, for two reasons: the session lacks scope, or the capability is REST-only.

The documented REST-only cases

The tools and gates page lists two names that are not on the hosted server: images_create and videos_create. Sume Image 1.0 and Video 1.0 stay REST-only, and the page points to the Developer API for them. For router stills and clips, the MCP tools are generate_image and generate_video. The page also says Higgsfield-only tool names are not hosted here.

An agent policy for gaps

When the model cannot find a tool, it should not give up or invent one. It should compare the two lists and report which surface carries the capability. The helper below shows the comparison with made-up names; the lists are illustrative, not real catalog output. It runs offline.

def gaps(catalog: set, tools: set) -> list:
    return sorted(catalog - tools)

def advice(name: str, tools: set) -> str:
    if name in tools:
        return name + ": call the MCP tool"
    return name + ": use the REST API, no MCP tool"

if __name__ == "__main__":
    catalog = {"image-a", "video-b", "audio-c"}   # illustrative
    tools = {"image-a", "audio-c"}                # illustrative
    for name in gaps(catalog, tools):
        print(advice(name, tools))

What to tell the user

If a capability is in the catalog but not in tools_list, there are three honest answers. It may need mcp:write, so ask the user whether to re-consent. It may be REST-only, so offer the Developer API. Or the session is stale, so refresh the list.

Never claim a tool exists because its name looks plausible. Call tools_schema with the exact name to read the contract before the first use.

Why a trimmed list misleads an agent

An agent can only reason about the tools it is shown. If it sees a trimmed list, it may report a limit that does not exist, or it may proceed with whichever tool looks closest. Both outcomes follow from the list you give it, not from the model's judgment.

Giving the agent a one-line summary of the catalog, or a rule to consult catalog_list when a tool is missing, avoids false refusals without widening the permission surface.

Checklist

Add these checks to any agent that routes between surfaces.

• Call tools_list and catalog_list once at start-up.
• Report the surface, not just a refusal.
• Re-read the tool list after a scope change.