get_topic_info

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Get detailed information' implying a read-only operation, but does not disclose behavior such as error handling if the topic does not exist, whether the match is exact or partial, or what 'detailed information' includes. The output schema may cover return structure, but the description itself adds little behavioral context.

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 concise: two sentences, with the first stating the purpose and the second documenting the parameter. It is front-loaded and to the point, though the parameter documentation could be integrated more formally. Overall, it earns its place without waste.

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 (one parameter, output schema exists), the description is minimally complete. It adequately states the purpose and parameter meaning. However, it lacks context about when to use this vs. sibling tools, and does not clarify expected behavior for missing topics or exact matching. The output schema likely covers return details, so the description is sufficient for a basic tool but not rich.

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?

The description explicitly explains the sole parameter: 'topic: Topic name to get info for'. This adds meaning beyond the schema, which only defines the parameter as a string with no description. Since schema description coverage is 0%, this compensation is valuable and clear for a single parameter.

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 clearly states the tool's function: 'Get detailed information about a research topic.' The verb 'Get' plus the resource 'research topic' makes the purpose explicit and distinguishes it from sibling tools like list_research_topics (which lists topics) and search_research_data (which searches data).

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 implies usage by specifying a topic name as input, but it does not explicitly state when to use this tool versus alternatives. There is no mention of using list_research_topics for browsing all topics or search_research_data for filtering. The context is clear enough for a simple tool, but exclusions or alternatives are not provided.

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