search_management

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

With zero annotations provided, the description carries the full behavioral disclosure burden, but it spends most of its space on design rationale and promotional claims ('THE gold standard!') rather than behavior. It does hint at external-source dependency and marks Pirate Bay as a 'fallback', yet never states that all operations are read-only network lookups, that metadata actions require API keys/PINs (api_key, pin appear only in the schema), or that three of the fourteen enum actions (tv_shows, tv_smart, ebooks_gutenberg) exist. An agent gets no safety profile, no failure-mode awareness, and no reliability expectations.

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

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

The one-line summary is front-loaded and the SEARCH SOURCES list is genuinely functional routing info. But the PORTMANTEAU PATTERN RATIONALE paragraph is meta-commentary an invoking agent does not need ('Follows FastMCP 2.12+ best practices'), and the promotional tone ('THE gold standard!', '60M+ books, 50M+ papers') inflates token count with low decision value. The description earns its place only partially; roughly half is functional, half is branding.

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

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

This is a high-complexity tool — 19 parameters, 14 dispatch actions, 5 external sources — and the description leaves major invocation gaps: three enum actions (tv_shows, tv_smart, ebooks_gutenberg) are entirely unexplained in both description and action schema text, and two parameters (new_only, downloaded_episodes) are completely undocumented. The presence of an output schema excuses return-value detail, but with a third of the action matrix uncharacterized and no composition guidance (e.g., search, then annas_detail), an agent cannot reliably use the full tool.

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

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

Schema description coverage is 89% (>80%), so the baseline of 3 applies. The schema already does the heavy lifting: the action enum spells out per-action required/optional parameters, and most parameters state which action consumes them. The description itself adds essentially no parameter-level meaning, and it does nothing to compensate for the actual gaps (new_only and downloaded_episodes have no descriptions; tv_shows, tv_smart, and ebooks_gutenberg are absent from the action enum's text).

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

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

The opening sentence names the domain ('search management'), the resources (torrents and metadata), and the consolidation model ('portmanteau tool'), while the SEARCH SOURCES section concretely scopes what the tool touches (nyaa.si, YTS, Anna's Archive, Pirate Bay, OMDb/TVDB). This is specific enough for an agent to route to it for search needs and to distinguish it from domain-disjoint siblings like legal_management or system_management. It stops short of 5 because it never addresses the potential boundary with torrent_management, and the phrased verb is nominal rather than a crisp search/dispatch verb.

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

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

The description gives real routing context: content types are mapped to sources (anime/manga/Japanese TV → nyaa.si, movies → YTS, ebooks → Anna's Archive, comics/ebooks fallback → Pirate Bay, metadata → OMDb/TVDB), and the rationale states that this tool replaces 11+ separate search tools. However, no sibling tool is ever named as an alternative, there is no when-NOT-to-use guidance, and the overlap risk with torrent_management is left unaddressed. Usage is implied rather than explicitly stated as a decision rule.

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