Tool Discovery and Model Cards Reference

class nomad.tool_search.ToolDescriptor(server, name, identifier, description, title, signature, arguments=(), wrappers_package='mcp_tools', schema=<factory>)

Searchable metadata for one MCP tool.

Parameters:

• server (str)

• name (str)

• identifier (str)

• description (str | None)

• title (str | None)

• signature (str)

• arguments (tuple[str, ...])

• wrappers_package (str)

• schema (dict[str, Any])

server: str

Server ID that exposes the tool.

name: str

Original MCP tool name.

identifier: str

Python-safe identifier used by generated wrappers.

description: str | None

Tool description from the MCP schema.

title: str | None

Optional human-readable tool title.

signature: str

Python-callable signature rendered from the tool schema.

arguments: tuple[str, ...]

Input argument names extracted from the input schema.

wrappers_package: str

Python package used as the root for generated wrappers.

schema: dict[str, Any]

Full MCP tool schema.

property python_import_path: str

schema_copy()

Return type:

dict[str, Any]

to_payload(*, detail_level)

Parameters:

detail_level (Literal['brief', 'full'])

Return type:

dict[str, Any]

to_wrapper_entry()

Return type:

dict[str, Any]

nomad.tool_search.build_tool_descriptors(server, tools, *, wrappers_package='mcp_tools')

Build searchable descriptors for tools exposed by one server.

Parameters:

• server (str)

• tools (Iterable[Any])

• wrappers_package (str)

Return type:

tuple[ToolDescriptor, …]

class nomad.tool_search.SupportsToolSearch(*args, **kwargs)

Protocol implemented by objects searchable with ToolSearchEngine.

server: str

name: str

title: str | None

description: str | None

arguments: tuple[str, ...]

python_import_path: str

class nomad.tool_search.ToolSearchEngine(descriptors, *, config=None)

Hybrid tool search using Tantivy retrieval plus deterministic reranking.

Parameters:

• descriptors (Sequence[SupportsToolSearch])

• config (SearchToolConfig | None)

search(query, *, limit=None)

Parameters:

• query (str | None)

• limit (int | None)

Return type:

list[SupportsToolSearch]

nomad.tool_search.search_tool_descriptors(descriptors, *, query, limit=None, config=None)

Rank descriptors by query text and return matching items.

Parameters:

• descriptors (Sequence[SupportsToolSearch])

• query (str | None)

• limit (int | None)

• config (SearchToolConfig | None)

Return type:

list[SupportsToolSearch]

nomad.tool_search.descriptor_payload(descriptor, *, detail_level, surface)

Render a descriptor payload for an MCP or code-mode search surface.

Parameters:

• descriptor (ToolDescriptor)

• detail_level (Literal['brief', 'full'])

• surface (Literal['mcp', 'code-mode'])

Return type:

dict[str, Any]

nomad.tool_search.register_search_tool(server, *, search_config, server_name='nomad')

Register the built-in search_tools tool on a FastMCP server.

Parameters:

• server (FastMCP)

• search_config (SearchToolConfig)

• server_name (str)

Return type:

None

class nomad.model_cards.ModelCardLocator

Locate README files for registered SciFM tools.

register(tool_name, source)

Associate a tool name with its resolved local path or repo id.

Parameters:

• tool_name (str)

• source (str | TypeAliasForwardRef('pathlib.Path'))

Return type:

None

registered_tools()

Return type:

Iterable[str]

read_model_card(tool_name)

Return the text contents of the README for the given tool.

Parameters:

tool_name (str)

Return type:

str

nomad.model_cards.register_model_card_tool(server, locator)

Register the built-in model card retrieval tool with the server.

Parameters:

• server (FastMCP)

• locator (ModelCardLocator)

Return type:

None

nomad.common.name_sanitize.sanitize_mcp_name(raw)

Convert a raw name into Nomad’s MCP-compatible tool-name form.

Parameters:

raw (str)

nomad.common.name_sanitize.sanitize_export_name(raw)

Convert a raw model source name into a safe export directory name.

Parameters:

raw (str)

Return type:

str

nomad.common.name_sanitize.sanitize_python_name(raw, *, module=False, allow_unicode=True)

Convert an arbitrary string into a safe Python identifier.

Parameters

rawstr

The input string to be sanitized.

modulebool, optional

If True, the returned name will be PEP‑8 compliant for modules (lower‑case, words separated by single underscores). Default is False.

allow_unicodebool, optional

If False, any non‑ASCII character is replaced with an underscore. Default is True.

Returns

str

A valid Python identifier that can be used as a function name, module name, variable name, etc.

Examples

>>> sanitize_python_name('my function! 2')
'my_function_2'
>>> sanitize_python_name('my function! 2', module=True)
'my_function_2'
>>> sanitize_python_name('class')
'class_'
>>> sanitize_python_name('def', module=True)
'def_'
>>> sanitize_python_name('2cool')
'_2cool'
>>> sanitize_python_name('!!!', module=True)
'module'

nomad.common.env.deep_interp_env(x)

Recursively interpolate environment variables in mappings or strings.

Parameters:

x (dict[str, Any] | str | Any)

nomad.common.env.interpolate_env(value)

Interpolate environment variables in a string.

Supported patterns:

${VAR}

→ value of VAR if set, otherwise empty string.

${VAR:DEFAULT}

→ value of VAR if set, otherwise DEFAULT.

Parameters:

value (str)

Return type:

str