Skip to main content
Glama

APITube News

by io.apitube

Resolve Taxonomy IDs

suggest
Read-only

Resolve a name or prefix to APITube taxonomy IDs so you can use them in the search_news tool's filters.

The search_news tool's most precise filters require IDs you cannot guess:

  • entity.id — numeric (persons, organizations, locations, brands, events...)

  • category.id — IPTC slug, e.g. "medtop:04000000"

  • topic.id — slug

  • industry.id — numeric

Use this tool FIRST to look those IDs up, then pass them into search_news.

USAGE:

  • type: which taxonomy to autocomplete — one of "entities", "categories", "topics", "industries".

  • prefix: the name (or its beginning) to search, e.g. "Tesla", "Elon", "spo".

Returns an array of matches; take the id of the best match and put it into search_news: suggest({ type: "entities", prefix: "Tesla" }) → [{ id: 12345, name: "Tesla, Inc.", ... }] search_news({ entity: { id: "12345" } })

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
typeYesWhich taxonomy to autocomplete.
prefixYesName or prefix to search, e.g. "Tesla", "Elon", "spo".

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite having readOnlyHint and openWorldHint annotations, the description adds substantial behavioral detail: it states the return type (array of matches), instructs the user to pick the best match's ID, and illustrates the output-to-input flow with inline examples. This goes well beyond what annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately long but highly structured: purpose, why needed, usage instructions, and a concrete example. Every sentence earns its place—no filler or repetition of schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema, the description fully compensates by showing the exact return structure and a complete usage example. It explains the different taxonomy ID formats and how to integrate with the sibling tool, making the whole workflow comprehensible.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers 100% of parameters with descriptions, so baseline is 3. The description adds value by providing concrete enum examples ('entities', 'categories', etc.) and prefix examples ('Tesla', 'Elon', 'spo'), plus explaining how the returned ID should be used in search_news.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Resolve') and identifies the exact resource (APITube taxonomy IDs) plus the downstream purpose (use in search_news filters). It clearly distinguishes this tool from its sibling search_news by explaining that this is a lookup step, not a search step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to 'Use this tool FIRST' and explains why (IDs cannot be guessed), with detailed guidance on which `type` values map to which ID formats. It also gives a concrete example of passing the result into search_news, making the intended workflow unmistakable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All APITube News toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.8/5.0
Disambiguation5/5

search_news handles article querying, filtering, and retrieval, while suggest is specifically a taxonomy-ID and autocomplete resolver. Even though search_news accepts some plain-text names, suggest's output is explicitly intended to feed into search_news, so the two tools are not in ambiguity.

Naming Consistency4/5

Both tool names use lowercase and an imperative style, with search_news following a clear verb_noun pattern. The odd one out is suggest, which is just a verb and would fit better as suggest_taxonomy_id, but there is no mixing of naming conventions.

Tool Count4/5

Although two tools is on the smaller side, the pair is well matched to the API's purpose: search_news is a very large query surface, and suggest handles the ID/taxonomy lookups that search_news needs. It feels slightly minimal but not unnecessary or insufficient.

Completeness5/5

The read-only news-domain workflow is covered end-to-end: search, filter, sort, paginate, select fields, retrieve article bodies, facet, highlight, and resolve taxonomy IDs. I do not see an obvious gap for the stated purpose of searching APITube News articles.

Resources