USCardForum MCP Server

get_topic_info

Retrieve topic metadata to plan pagination before reading posts, including title, post count, and timestamps from USCardForum discussions.

Instructions

Get metadata about a specific topic without fetching all posts.

Args:
    topic_id: The numeric topic ID (from URLs like /t/slug/12345)

Use this FIRST before reading a topic to:
- Check how many posts it contains (for pagination planning)
- Get the topic title and timestamps
- Decide whether to fetch all posts or paginate

Returns a TopicInfo object with:
- topic_id: The topic ID
- title: Full topic title
- post_count: Total number of posts
- highest_post_number: Last post number (may differ from count if posts deleted)
- last_posted_at: When the last reply was made

Strategy for large topics:
- <50 posts: Safe to fetch all at once
- 50-200 posts: Consider using max_posts parameter
- >200 posts: Fetch in batches or summarize key posts

Input Schema

TableJSON Schema

Name	Required	Description	Default
`topic_id`	Yes	The numeric topic ID (from URLs like /t/slug/12345)

Output Schema

TableJSON Schema

Name	Required	Description
`title`	No	Topic title
`topic_id`	Yes	Topic identifier
`post_count`	No	Total number of posts
`last_posted_at`	No	Last activity time
`highest_post_number`	No	Highest post number

Schema Changelog

Changes observed during successful MCP inspections.

First observedDec 30, 2025

TDQS

A4.7/5.0

Behavior4/5

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 effectively describes the tool's behavior: it's a read-only operation (implied by 'Get metadata'), returns a TopicInfo object with specific fields, and includes practical advice on handling large topics (e.g., pagination strategies). It doesn't mention rate limits or auth needs, but covers key operational aspects well.

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 well-structured and front-loaded, starting with the core purpose, followed by args, usage guidelines, return values, and strategy. Every sentence adds value—no redundancy or fluff—making it efficient and easy to parse.

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?

Given the tool's complexity (single parameter, read-only operation) and the presence of an output schema (which covers return values), the description is complete. It explains purpose, usage, parameters, and behavioral context without needing to detail return values, making it sufficient for an agent to use the tool effectively.

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 has 100% description coverage, so the baseline is 3. The description adds value by explaining the parameter's source ('from URLs like /t/slug/12345') and its role in the tool's purpose, enhancing understanding beyond the schema's basic documentation. It doesn't add syntax details, but provides contextual meaning.

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 clearly states the tool's purpose: 'Get metadata about a specific topic without fetching all posts.' It uses a specific verb ('Get metadata') and resource ('specific topic'), and explicitly distinguishes it from sibling tools like 'get_all_topic_posts' and 'get_topic_posts' by emphasizing it doesn't fetch posts.

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 provides explicit guidance on when to use this tool: 'Use this FIRST before reading a topic' for checking post count, title, timestamps, and deciding on fetching strategy. It distinguishes from alternatives by noting it's for metadata only, not for fetching posts, and offers a strategy for large topics with specific thresholds (<50, 50-200, >200 posts).

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