Browse journal lists and rankings (special-issue CFPs, CCF, highest impact factor, popularity, all), paginated. No keyword filtering — use search_journals for that.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based | |
| ranking | Yes | cfp=special-issue calls for papers; ccf=CCF list; highest_if=highest impact factor; most_viewed/most_tracked=popularity; all=all journals | |
| per_page | No | Items per page, max 100 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds behavioral context beyond that: it is paginated and supports multiple list types. It could also mention that no filtering is possible, but it does state that clearly, which helps set 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 description is two sentences, front-loaded with the main purpose, and includes a clear exclusion with an alternative tool. Every word serves a purpose; no redundant or vague language.
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?
Given the tool's simplicity and the richness of the schema (100% coverage) plus annotations, the description provides the necessary context: what the tool does, that it is paginated, and how it differs from search_journals. It does not describe return values, but no output schema exists and the outcome is reasonably inferable from the 'browse' phrasing.
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 100%, so parameters are already documented. The description adds minor semantic value by explaining what each ranking type means (e.g., 'special-issue CFPs'), but this largely mirrors the schema's enum descriptions. No additional meaning is provided for page or per_page beyond the schema.
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 description uses a specific verb ('Browse') and identifies the resource ('journal lists and rankings') with concrete examples (CFPs, CCF, impact factor, popularity). It also distinguishes itself from the sibling search_journals by explicitly stating it has no keyword filtering.
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?
Provides clear usage guidance: when to use this tool (browsing lists) and when not to (keyword search), naming the alternative tool explicitly. The different ranking options are also described, giving context for choosing a parameter value.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a clearly distinct purpose: get individual entities (conference, journal, researcher), get statistics, browse lists, or search. There is no overlap; list vs search are differentiated by predefined rankings vs keyword filtering.
All tools follow a consistent verb_noun pattern in snake_case: get_*, list_*, search_*. The verbs are appropriate and predictable, with no mixing of conventions.
8 tools is well-scoped for a read-only academic venue information service. It covers retrieval, browsing, searching, and statistics without excess or deficiency.
The tool surface covers all expected operations for the domain: individual entity retrieval (conference, journal, researcher), browsing (lists), searching (conferences/journals), and site statistics. Related data is included in entity details, and intentional gaps (no researcher search) are documented.
