topic_landscape

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

With no annotations, the description carries the full burden and does so well: it discloses sampling behaviour (max_papers up to 2000, most recent by default), that coverage is stated, that proceedings/book series are counted separately by default, that the same paper can count in multiple categories, and that Scopus search entitlement is required. These are non-obvious operational traits an agent must know.

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 two core outputs are front-loaded before the counting rules and sampling caveats. It is a dense paragraph with minor verbosity in the venue-type caveat, but essentially every sentence carries decision-relevant information.

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?

With no output schema, the description must explain what comes back, and it does: papers per subject area plus per-category Q1–Q4 counts, main journals, separate proceedings/book reporting, and the venue-type mix. Nothing essential for correct invocation is missing.

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 a baseline of 3 applies, but the description adds genuine semantics: the rationale for 'sample' (most cited to see where influential work appears), the quartile-counting meaning of journals_only, and the max_papers cap of 2000. It reinforces rather than merely repeats 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 first sentence names the exact output of interest ('where and at what prestige a topic is published') and the second specifies the two reports produced. This is a specific verb+resource definition that clearly separates it from generic siblings like search_scopus or publication_counts.

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 conveys a clear context (analysing a topic's venue/prestige distribution via a Scopus query) but never states when to choose it over alternatives such as publication_counts or get_journal_metrics, nor any exclusions. Usage is implied by the described output rather than stated as guidance.

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