Инструменты обнаружения

Инструменты обнаружения позволяют LLM навигировать по иерархии спецификаций: найти все спецификации, углубиться в спецификацию для просмотра коллекций и исследовать теги внутри коллекции. Начните с spec_list, чтобы увидеть доступные API, затем используйте ID для дальнейшего углубления.

---

spec_list

Назначение

Список всех спецификаций API, зарегистрированных в рабочей области. Это отправная точка для любой сессии — LLM вызывает его первым, чтобы узнать, какие API доступны.

Когда использовать

• В начале сессии, чтобы увидеть, какие API настроены
• После добавления или удаления спецификаций для обновления списка
• Когда нужен ID спецификации для других инструментов

Как работает

Возвращает список всех спецификаций с их уникальным ID и доменным именем. Параметры не требуются.

Параметры

Нет.

Ответ

{
  "specs": [
    {
      "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "domain": "meteo"
    },
    {
      "id": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
      "domain": "dadjoke"
    }
  ]
}

Поле	Тип	Описание
id	string	32-символьный MD5-хеш, уникальный идентификатор спецификации
domain	string	Доменное имя спецификации (например, "meteo", "dadjoke")

Нюансы

• Возвращает только id и domain — для полных деталей (коллекции, теги) используйте spec_by_id
• Все ID — 32-символьные MD5-строки в шестнадцатеричном формате (^[0-9a-f]{32}$)
• Если спецификации не настроены, возвращает пустой массив

---

spec_by_id

Назначение

Получение детальной информации о конкретной спецификации: её домен, все коллекции и их статистика (количество тегов, количество методов).

Когда использовать

• После spec_list для просмотра коллекций внутри спецификации
• Когда нужны ID коллекций для дальнейшей навигации

Как работает

Принимает ID спецификации и возвращает метаданные спецификации плюс все её коллекции с количественными показателями.

Параметры

Параметр	Тип	Обязательный	Описание
id	string	Да	32-символьный MD5-хеш спецификации

Ответ

{
  "spec": {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "domain": "meteo"
  },
  "collections": [
    {
      "id": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
      "title": "Weather Forecast",
      "llmTitle": "Forecast API",
      "countTags": 3,
      "countMethods": 12
    }
  ]
}

Поле	Тип	Описание
spec.id	string	Идентификатор спецификации
spec.domain	string	Доменное имя спецификации
collections[].id	string	Идентификатор коллекции
collections[].title	string	Человекочитаемое название
collections[].llmTitle	string	Название для LLM (опционально)
collections[].countTags	int	Количество тегов в коллекции
collections[].countMethods	int	Количество HTTP-методов в коллекции

Нюансы

• Возвращает ошибку not_found, если ID спецификации не существует
• id должен быть валидной 32-символьной MD5-строкой в шестнадцатеричном формате

---

collection_by_spec

Назначение

Список всех коллекций в конкретной спецификации. Аналогично spec_by_id, но возвращает только список коллекций без дополнительных метаданных спецификации.

Когда использовать

• Когда уже есть ID спецификации и нужен только список коллекций
• Как более лёгкая альтернатива spec_by_id

Параметры

Параметр	Тип	Обязательный	Описание
specId	string	Да	32-символьный MD5-хеш спецификации

Ответ

{
  "spec": {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "domain": "meteo"
  },
  "collections": [
    {
      "id": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
      "title": "Weather Forecast",
      "llmTitle": "Forecast API",
      "countTags": 3,
      "countMethods": 12
    }
  ]
}

Нюансы

• Возвращает not_found, если спецификация не существует
• Те же данные, что и spec_by_id, но без дополнительной обёртки спецификации

---

collection_by_id

Назначение

Получение детальной информации о конкретной коллекции: её метаданные, родительская спецификация и все теги внутри коллекции.

Когда использовать

• После collection_by_spec для просмотра тегов внутри коллекции
• Когда нужны ID тегов для tag_by_id или endpoint_by_tag

Параметры

Параметр	Тип	Обязательный	Описание
id	string	Да	32-символьный MD5-хеш коллекции

Ответ

{
  "spec": {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "domain": "meteo"
  },
  "collection": {
    "id": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
    "title": "Weather Forecast",
    "countMethods": 12
  },
  "tags": [
    {
      "id": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
      "title": "forecast",
      "countMethods": 5
    },
    {
      "id": "e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7",
      "title": "current",
      "countMethods": 7
    }
  ]
}

Поле	Тип	Описание
spec	object	Родительская спецификация (id, domain)
collection	object	Метаданные коллекции (id, title, countMethods)
tags[]	array	Список тегов с id, title, countMethods

Нюансы

• Возвращает not_found, если ID коллекции не существует
• Теги возвращаются с их ID — используйте endpoint_by_tag(tagId) для просмотра фактических эндпоинтов

---

tag_by_spec

Назначение

Список всех тегов во всей спецификации, охватывающий все коллекции. Полезно для получения общего обзора всех доступных тегов.

Когда использовать

• Когда нужно увидеть все теги в спецификации без углубления в каждую коллекцию
• Когда неизвестно, в какой коллекции находится нужный тег

Параметры

Параметр	Тип	Обязательный	Описание
specId	string	Да	32-символьный MD5-хеш спецификации

Ответ

{
  "tags": [
    {
      "id": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
      "title": "forecast",
      "countMethods": 5
    },
    {
      "id": "e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7",
      "title": "current",
      "countMethods": 7
    }
  ]
}

Нюансы

• Возвращает not_found, если спецификация не существует
• Теги агрегируются из всех коллекций спецификации

---

tag_by_collection

Назначение

Список всех тегов в конкретной коллекции. В отличие от tag_by_spec, также возвращает метаданные родительской спецификации и коллекции.

Когда использовать

• После collection_by_id для подтверждения списка тегов
• Когда нужен полный контекст (спецификация + коллекция + теги)

Параметры

Параметр	Тип	Обязательный	Описание
collectionId	string	Да	32-символьный MD5-хеш коллекции

Ответ

{
  "spec": {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "domain": "meteo"
  },
  "collection": {
    "id": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
    "title": "Weather Forecast",
    "countMethods": 12
  },
  "tags": [
    {
      "id": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
      "title": "forecast",
      "countMethods": 5
    }
  ]
}

Нюансы

• Возвращает not_found, если коллекция не существует
• Те же данные тегов, что и tag_by_spec, но ограниченные одной коллекцией

---

tag_by_id

Назначение

Получение информации об одном теге: его ID, название и количество методов. Это рассказывает о самом теге — для просмотра фактических эндпоинтов используйте endpoint_by_tag.

Когда использовать

• Когда есть ID тега и нужно подтвердить его имя и размер
• Перед вызовом endpoint_by_tag для понимания, сколько эндпоинтов ожидать

Параметры

Параметр	Тип	Обязательный	Описание
id	string	Да	32-символьный MD5-хеш тега

Ответ

{
  "tag": {
    "id": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
    "title": "forecast",
    "countMethods": 5
  }
}

Поле	Тип	Описание
tag.id	string	Идентификатор тега
tag.title	string	Человекочитаемое имя тега
tag.countMethods	int	Количество HTTP-методов в этом теге

Нюансы

• Возвращает not_found, если тег не существует
• Этот инструмент возвращает только метаданные тега — используйте endpoint_by_tag для получения фактического списка эндпоинтов