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

With no annotations provided, the description carries full burden and does well: it discloses authentication requirement ('REQUIRES AUTHENTICATION'), mentions the return type ('Returns a Bookmark object'), and describes auto-delete behavior with default values. It doesn't cover rate limits or error conditions, but provides substantial operational 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?

Well-structured with purpose statement, authentication warning, parameter details, prerequisite, return value, and usage context. The auto_delete_preference explanation is somewhat lengthy but informative. Overall efficient with minimal redundancy.

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?

For a mutation tool with no annotations but an output schema, the description provides good coverage: clear purpose, authentication requirement, parameter guidance, return type mention, and usage context. It could mention potential errors or idempotency, but covers the essential operational aspects adequately.

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 baseline is 3. The description adds value by explaining the auto_delete_preference enum values in detail (0-3 with meanings) and clarifying that name, reminder_type, and reminder_at are optional. It doesn't add syntax details beyond schema, but the enum explanation is helpful.

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 verb ('bookmark') and resource ('a post'), specifying it's for 'later reference'. It distinguishes from sibling tools like 'get_topic_posts' or 'get_user_actions' by focusing on saving rather than retrieving content.

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?

Explicitly states 'Must call login() first' for authentication prerequisites and 'Use to save interesting posts for later reference' for context. It doesn't mention alternatives, but the authentication requirement and purpose provide clear usage boundaries.

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

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

With no annotations provided, the description carries full burden and does an excellent job disclosing behavioral traits. It explains automatic pagination handling, safety considerations for large topics, and the relationship between parameters like start_post_number and max_posts. It also clarifies the return structure matches 'get_topic_posts' but for all matching posts.

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 perfectly structured and front-loaded with the core purpose, followed by organized sections for arguments, important notes, use cases, returns, and pro tips. Every sentence earns its place by providing essential information without redundancy, making it both comprehensive and efficient.

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 complexity (5 parameters, automatic pagination) and the presence of an output schema (which handles return values), the description is complete. It covers purpose, usage guidelines, parameter interactions, behavioral traits, and relationships with sibling tools, leaving no significant gaps for agent understanding.

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?

With 100% schema description coverage, the baseline is 3, but the description adds significant value beyond the schema. It explains how parameters interact (e.g., 'end_post_number fetches to end if not set'), provides practical examples of parameter combinations, and clarifies the safety purpose of max_posts. The 'Pro tip' section adds contextual guidance about parameter usage.

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 purpose with specific verbs ('fetch all posts from a topic') and distinguishes it from sibling tools like 'get_topic_posts' by emphasizing automatic pagination. It explicitly mentions fetching entire topics versus manual pagination alternatives.

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 provides explicit guidance on when to use this tool versus alternatives, including specific use cases with parameter examples. It advises using 'get_topic_info first to check post_count before deciding whether to fetch all or paginate manually,' and includes an 'IMPORTANT' note about limiting response size for large topics.

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

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

With no annotations provided, the description carries full burden and does well by specifying the return type ('CategoryMap object'), scope ('all forum categories'), structure ('includes both main categories and subcategories'), and provides concrete examples of common categories. It doesn't mention rate limits, authentication needs, or pagination behavior, but covers the essential operational 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 well-structured and front-loaded with the core purpose in the first sentence. Each subsequent paragraph adds value: output format, category purpose, concrete examples, usage scenarios, and scope clarification. No wasted sentences or redundant 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?

Given the tool's simplicity (0 parameters, has output schema), the description is complete. It explains what the tool does, what it returns, why categories matter, provides examples, and outlines usage scenarios. The output schema will handle return value details, so the description appropriately focuses on higher-level context.

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?

With 0 parameters and 100% schema description coverage, the baseline would be 4. The description appropriately doesn't discuss parameters since none exist, and instead focuses on the tool's purpose and output. No parameter information is needed or expected.

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 specific action ('Get a mapping'), resource ('all forum categories'), and output format ('CategoryMap object with category_id to category name mapping'). It distinguishes this tool from siblings like get_hot_topics or get_new_topics by focusing on category metadata rather than topic content.

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 provides clear context for when to use this tool ('Use category IDs to filter search results, understand topic sections, navigate to areas of interest'), but doesn't explicitly state when NOT to use it or name specific alternatives among sibling tools. The guidance is practical but lacks explicit exclusions.

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

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 describes the return structure (Session object with fields) and implies a read-only operation by focusing on information retrieval, but lacks details on error handling, rate limits, or permissions required. This is adequate but has gaps for a tool with no annotation support.

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 highly concise and well-structured: it starts with the core purpose, lists return details in a bulleted format, and ends with usage guidance. Every sentence adds value without redundancy, making it easy for an agent to parse quickly.

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 low complexity (0 parameters, no annotations, but has an output schema), the description is mostly complete. It explains what the tool does and what it returns, leveraging the output schema to avoid detailing return values. However, it could improve by mentioning potential errors or edge cases (e.g., what happens if no session exists).

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 tool has 0 parameters with 100% schema description coverage, so the schema fully documents the inputs. The description appropriately adds no parameter details, focusing instead on output semantics. This meets the baseline for zero parameters, but doesn't exceed it by explaining context or assumptions.

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 purpose as 'Get information about the current session' with specific details about what information is returned (authentication status and user info). It distinguishes itself from siblings by focusing on session status rather than content retrieval like get_topic_posts or user data like get_user_summary, though it doesn't explicitly name these distinctions.

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 provides clear usage guidance with 'Use to verify authentication status,' which tells the agent when to invoke this tool. However, it doesn't explicitly state when not to use it or name specific alternatives (e.g., using login for authentication attempts), keeping it from a perfect score.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns ranked results based on engagement metrics, includes pagination behavior (0-indexed, page=1 for more topics), and describes the return format with example interpretation. However, it doesn't mention rate limits, authentication requirements, or error conditions, leaving some behavioral aspects uncovered.

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 well-structured with clear sections: purpose statement, use cases, parameters, return format, and example interpretation. Every sentence adds value without redundancy, and it's front-loaded with the core functionality. The length is appropriate for the tool's complexity.

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 has an output schema (implied by the detailed return format description) and 100% schema coverage for its single parameter, the description is complete. It covers purpose, usage, parameters, return values, and behavioral context, leaving no significant gaps for an AI agent to understand and invoke the tool correctly.

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 the schema already documents the 'page' parameter. The description adds value by explaining the pagination logic ('0-indexed', 'Use page=1 to get more topics') and contextualizing it within the tool's purpose, though it doesn't provide additional syntax or format details 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 clearly states the verb 'fetch' and resource 'currently trending/hot topics from USCardForum', specifying the ranking criteria (engagement metrics like recent replies, views, and likes). It distinguishes from siblings like 'get_top_topics' or 'get_new_topics' by focusing on current trending/active discussions rather than all-time top or newly created topics.

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 explicitly provides three use cases ('See what the community is currently discussing', 'Find breaking news or time-sensitive opportunities', 'Discover popular ongoing discussions'), which clearly indicate when to use this tool. It implies alternatives by mentioning other tools like 'get_topic_posts' for detailed topic information, though it doesn't explicitly name all sibling tools.

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

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 key behaviors: it's a read operation (implied by 'fetch' and 'returns'), returns sorted data (newest first), and mentions pagination. However, it lacks details on rate limits, error handling, or authentication needs, which would be beneficial for a tool with no annotations.

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 well-structured and front-loaded, starting with the core purpose, followed by usage guidelines, args, returns, and a tip. Every sentence adds value without redundancy, and it efficiently conveys necessary information in a compact format.

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 low complexity (1 optional parameter), 100% schema coverage, and the presence of an output schema (implied by the returns description), the description is complete. It covers purpose, usage, parameters, and return values adequately, leaving no significant gaps for an AI agent to understand and invoke the tool correctly.

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 schema description coverage is 100%, so the schema already documents the 'page' parameter. The description adds value by explaining pagination semantics ('0-indexed', 'Use page=1 to get more topics') and providing practical usage context, though it doesn't introduce new parameters or details beyond the schema's scope.

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 purpose with specific verbs ('fetch', 'returns') and resource ('latest/newest topics from USCardForum'), distinguishing it from siblings like get_hot_topics or get_top_topics by emphasizing recency and freshness. It explicitly mentions sorting by creation time and that topics may have fewer replies, which differentiates it from tools focused on popularity or engagement.

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 provides explicit usage scenarios with bullet points (e.g., 'Find newly posted deals or offers', 'See fresh questions from the community'), and the 'Tip' section offers additional context on when topics might be important. It implicitly distinguishes from siblings by focusing on newness rather than hotness or top topics, though it doesn't explicitly name alternatives.

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

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

With no annotations provided, the description carries full burden and does well by disclosing authentication requirements ('REQUIRES AUTHENTICATION', 'Must call login() first'), return format details, and filtering behavior. However, it doesn't mention rate limits, pagination, or error conditions, which would be helpful for a notification-fetching tool.

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 well-structured with clear sections (purpose, authentication warning, parameters, returns, use cases). It's appropriately sized at 12 sentences, though the 'Args' section duplicates schema information and could be more concise. Most sentences earn their place by providing distinct value.

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 moderate complexity, 100% schema coverage, and presence of an output schema (implied by the detailed return description), the description is complete enough. It covers authentication, parameters, return format, and use cases without needing to explain return values since the output schema handles that.

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 the schema already documents all three parameters completely. The description repeats parameter information in the 'Args' section but doesn't add meaningful context beyond what's in the schema (e.g., typical ID ranges, practical limit values). Baseline 3 is appropriate when schema does the heavy lifting.

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 specific action ('Fetch your notifications') and resource ('notifications'), distinguishing it from siblings like get_user_actions or get_user_replies. It explicitly mentions what notifications contain (replies, mentions, likes, topic updates), which helps differentiate its purpose from other user-related tools.

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 provides explicit guidance on when to use this tool ('Check for new replies to your posts', 'See mentions and likes', 'Track topic updates you're watching') and includes a crucial prerequisite ('Must call login() first'). It also distinguishes usage from other notification-related tools by specifying the scope (personal notifications only).

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

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 metadata fetch (implied by 'get'), returns a structured TopicInfo object, and includes strategic advice for handling large topics (e.g., safe thresholds, batching). However, it doesn't mention potential errors, rate limits, or authentication needs, leaving minor gaps.

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 well-structured and appropriately sized, with clear sections for purpose, args, usage, returns, and strategy. Most sentences earn their place, but the strategy section could be slightly more concise. Overall, it's front-loaded with key information and avoids unnecessary repetition.

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 complexity (single parameter, read-only metadata fetch), the description is complete. It covers purpose, usage, parameters, and behavioral context, and since an output schema exists (as indicated by context signals), it doesn't need to detail return values—though it still does for clarity. This addresses all necessary aspects without redundancy.

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 schema description coverage is 100%, so the schema already documents the topic_id parameter. The description adds value by explaining the parameter's semantics: it's numeric and derived from URLs like '/t/slug/12345', which clarifies the format beyond the schema's basic type. This extra context justifies a score above the baseline of 3.

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 purpose: 'Get metadata about a specific topic without fetching all posts.' It specifies the verb ('get metadata'), resource ('specific topic'), and 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.

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 whether to fetch all posts or paginate. It also distinguishes it from alternatives by noting it's for metadata only, not fetching posts.

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

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

With no annotations provided, the description carries full burden and does an excellent job disclosing key behavioral traits: it specifies the batch size (~20 posts per call), pagination logic (starting from post_number), and return format (list of Post objects with detailed fields). It also clarifies default behaviors and the effect of include_raw. No contradictions exist, and it covers most essential operational aspects.

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 well-structured with clear sections (purpose, parameters, returns, pagination example) and front-loads the core functionality. Every sentence earns its place by providing essential information, though the parameter section duplicates schema content unnecessarily. It could be more concise by omitting the redundant parameter descriptions.

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 moderate complexity (paginated fetching), no annotations, and the presence of an output schema (implied by the detailed return description), the description is complete. It covers purpose, usage, parameters, return format, and pagination behavior thoroughly. The output schema equivalent in the description eliminates any need for additional return value explanation.

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 the schema already documents all three parameters thoroughly. The description repeats the parameter explanations verbatim in the 'Args' section, adding no additional semantic value beyond what's in the schema. However, it does provide context about how parameters interact (e.g., post_number as starting point for pagination), which slightly elevates it above baseline.

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 specific action ('fetch a batch of posts from a topic') and resource ('posts'), distinguishing it from siblings like 'get_all_topic_posts' (which presumably fetches all posts at once) and 'get_topic_info' (which likely fetches metadata). The verb 'fetch' combined with the pagination context makes the purpose unambiguous.

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 explicitly states when to use this tool ('use for paginated reading of topics') and provides a detailed pagination example with steps. It implicitly distinguishes from 'get_all_topic_posts' by emphasizing batch fetching with a starting position, though it doesn't name alternatives directly. The guidance on pagination behavior is comprehensive.

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

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

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it describes the return format (TopicSummary objects), sorting behavior (by engagement score), and pagination mechanics (0-indexed). It could improve by mentioning rate limits or authentication requirements.

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?

Perfectly structured and appropriately sized: purpose statement first, then parameter details, usage guidelines, return information, and examples. Every sentence serves a distinct purpose with zero wasted words, and the information is well-organized for quick comprehension.

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 has an output schema (so return values don't need explanation), 100% schema coverage, and no annotations, the description provides excellent completeness: it covers purpose, parameters, usage scenarios, return format, sorting behavior, and includes helpful examples. Nothing essential 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 the baseline is 3. The description adds some value by providing concrete examples of period values and explaining what each represents, but doesn't add significant semantic meaning beyond what's already in the well-documented 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 clearly states the verb 'fetch' and resource 'top-performing topics' with the specific scope 'for a specific time period'. It distinguishes from siblings like get_hot_topics or get_new_topics by emphasizing performance ranking over recency or popularity metrics.

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 'Use this to:' section provides clear context for when to use this tool (finding valuable discussions, researching historical threads, identifying evergreen content). However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools.

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

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 mentions the tool returns 'a list of UserAction objects' and describes pagination behavior via the offset parameter, but doesn't cover important aspects like rate limits, authentication requirements, error conditions, or what happens when username doesn't exist. It adds some context but leaves gaps for a tool with no annotation coverage.

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 well-structured with clear sections (purpose, args, returns, usage guidance) and every sentence adds value. It could be slightly more concise by avoiding repetition of filter values that are already in the schema, but overall it's efficiently organized and front-loaded with the core purpose.

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 that there's an output schema (returns UserAction objects), the description doesn't need to explain return values. It covers the tool's purpose, parameters, and usage context adequately. The main gap is the lack of behavioral details that would normally come from annotations (auth, rate limits, errors), but the description provides sufficient context for basic usage given the output schema exists.

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 the schema already fully documents all parameters. The description adds minimal value beyond the schema - it repeats the filter mapping (1=likes given, etc.) and offset explanation, but doesn't provide additional semantic context like parameter interactions or edge cases. Baseline 3 is appropriate when schema does the heavy lifting.

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 purpose with specific verb ('Fetch') and resource ('user's activity feed'), and distinguishes it from siblings by mentioning 'detailed activity analysis beyond just replies.' It explicitly names alternatives (get_user_replies, get_user_topics), showing clear differentiation.

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 provides explicit guidance on when to use this tool ('for detailed activity analysis beyond just replies') and when to use alternatives ('For most cases, get_user_replies or get_user_topics are simpler'). This gives clear context for tool selection versus sibling tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool fetches data (implied read-only) and explains the significance of badges (e.g., milestones, recognition), adding useful context. However, it lacks details on behavioral traits like error handling, rate limits, or authentication needs, which are important for a tool with user data.

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 well-structured with sections for purpose, args, returns, and usage, making it easy to scan. It is appropriately sized, but the parameter descriptions are redundant with the schema, slightly reducing efficiency. Most sentences earn their place by adding value beyond the schema.

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 that an output schema exists (implied by 'Returns a UserBadges object'), the description does not need to detail return values, and it adequately explains the tool's purpose and usage. With no annotations and 100% schema coverage, it provides sufficient context for a read operation, though it could benefit from more behavioral details like error cases.

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 the schema already fully documents both parameters. The description repeats the parameter descriptions verbatim ('username: The user's handle', 'grouped: Group badges by type') without adding extra meaning, such as format constraints or examples. Baseline 3 is appropriate as the schema handles the heavy lifting.

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 verb 'Fetch' and resource 'badges earned by a user', making the purpose specific and unambiguous. It distinguishes from siblings like 'get_user_summary' or 'list_users_with_badge' by focusing on individual user badges rather than summaries or badge-wide listings.

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 provides clear context for usage ('Use to assess user experience and trustworthiness') and implies when to use it (for badge-related user assessment). However, it does not explicitly state when not to use it or name alternatives among siblings, such as 'get_user_summary' for broader user data.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions pagination and the return structure, but doesn't cover important aspects like rate limits, authentication requirements, error conditions, or whether this is a read-only operation. The description adds some context about follower count significance, but this is more commentary than behavioral transparency.

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 well-structured with clear sections for purpose, arguments, and returns. The final sentence about follower count significance, while potentially helpful for context, doesn't directly aid tool invocation and could be considered extraneous. Overall, it's appropriately sized and front-loaded with the core functionality.

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 that there's an output schema (implied by the return description), the description doesn't need to fully explain return values. It covers the basic purpose and parameters adequately. However, for a tool with no annotations and multiple sibling tools in the same domain, more contextual guidance about when to use this specific tool would improve completeness.

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 the schema already fully documents both parameters. The description repeats the parameter information without adding meaningful semantic context beyond what's in the schema. It doesn't explain format requirements for 'username' or how pagination works in practice.

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 purpose with a specific verb ('Fetch') and resource ('list of users following a specific user'), making it immediately understandable. However, it doesn't explicitly differentiate from its sibling 'get_user_following', which likely retrieves users that a specific user is following rather than followers of that user.

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 provides no guidance on when to use this tool versus alternatives like 'get_user_following' or 'get_user_summary'. It mentions pagination but doesn't explain when pagination is needed or how to handle large result sets. No prerequisites or exclusions are stated.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a FollowList object with users and total_count, adding value beyond the input schema. However, it lacks details on behavioral traits such as rate limits, authentication needs, error handling, or whether it's a read-only operation (implied by 'fetch' but not explicit).

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 well-structured with clear sections (purpose, args, returns, use cases) and is appropriately sized. It avoids unnecessary details, but the 'Args:' and 'Returns:' sections slightly repeat schema info, which could be more concise. Overall, it's front-loaded and efficient.

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 low complexity, 100% schema coverage, and presence of an output schema (implied by the returns description), the description is fairly complete. It covers purpose, parameters, returns, and usage guidelines. However, without annotations, it could benefit from more behavioral context like safety or performance details.

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 the schema already documents both parameters (username and page). The description repeats the parameter info in the 'Args:' section but does not add significant meaning beyond what the schema provides, such as format examples or constraints. Baseline 3 is appropriate as the schema handles most documentation.

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 purpose with 'Fetch the list of users that a user follows,' specifying the verb (fetch) and resource (list of users followed). It distinguishes from sibling tools like get_user_followers, which fetches followers rather than following. However, it doesn't explicitly differentiate from all siblings, such as get_user_summary, which might include similar 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 'Use to:' section provides clear context for when to use this tool, listing purposes like discovering influential users and mapping social connections. It implies usage scenarios but does not explicitly state when not to use it or name alternatives (e.g., get_user_followers for a different perspective).

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

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 mentions pagination via the offset parameter and describes the return type (UserReactions object), but doesn't address important behavioral aspects like rate limits, authentication requirements, error conditions, or what happens with invalid usernames. The description adds some context about the purpose of reaction data but lacks operational transparency.

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 well-structured and appropriately sized with clear sections: purpose statement, args documentation, return statement, and usage context. Each sentence serves a purpose, though the parameter documentation slightly duplicates schema information. The description is front-loaded with the core purpose statement.

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 has an output schema (returns UserReactions object), the description doesn't need to explain return values in detail. With 2 parameters and 100% schema coverage, the description provides adequate context for this read-only data retrieval tool. However, for a tool with no annotations, it could benefit from more behavioral context about authentication, rate limits, or error handling.

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 the schema already fully documents both parameters. The description repeats the parameter explanations ('username: The user's handle', 'offset: Pagination offset') without adding meaningful semantic context beyond what's in the schema. No additional guidance on username format, offset usage patterns, or parameter interactions is provided.

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 purpose with 'Fetch a user's post reactions (likes, etc.)' - a specific verb (fetch) and resource (user's post reactions). It distinguishes from siblings like get_user_actions or get_user_summary by focusing specifically on reactions. However, it doesn't explicitly contrast with get_user_replies or get_user_topics which might also involve user content interactions.

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 provides implied usage context with 'Use to see what content a user has reacted to, which can indicate their interests and values.' This suggests when to use it (for interest/value analysis), but doesn't explicitly state when NOT to use it or name specific alternatives among the many sibling tools. No guidance on prerequisites or error conditions is provided.

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

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 fetch operation (implied by 'Fetch'), returns paginated results with specific increments of 30, and provides detailed information about the return format (UserAction objects with specific fields). The description doesn't mention rate limits, authentication requirements, or error conditions, but provides substantial behavioral context for a read operation.

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 well-structured and appropriately sized. It starts with the core purpose, then provides parameter details, return format, use cases, and pagination guidance. Every sentence adds value: the parameter section clarifies inputs, the return format section explains outputs, and the use cases provide practical guidance. No wasted words or redundant 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?

Given that this is a read operation with no annotations, 100% schema coverage, and an output schema (implied by the detailed return format description), the description is complete. It covers purpose, parameters, return values, use cases, and pagination behavior. The output schema information in the description ('Returns a list of UserAction objects with...') compensates for the lack of formal output schema, making this description comprehensive for the tool's complexity.

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 the schema already fully documents both parameters. The description repeats the parameter information ('Args: username: The user's handle, offset: Pagination offset') without adding significant semantic value beyond what's in the schema. It does add the pagination increment detail ('in increments of 30'), which provides useful context but doesn't fundamentally change parameter understanding.

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 purpose with specific verb ('Fetch') and resource ('replies/posts made by a user in other topics'), distinguishing it from sibling tools like get_user_topics (which likely gets topics created by a user) and get_user_actions (which might include broader actions beyond replies). The description explicitly mentions what makes this tool unique: focusing on user contributions across different topics.

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 provides explicit guidance on when to use this tool ('Use this to: See a user's contributions across topics, Find their data points and experiences, Evaluate the quality of their participation'). It distinguishes this from tools that might focus on a single topic (like get_topic_posts) or broader user actions (like get_user_actions), giving clear use cases without needing to explicitly list exclusions.

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

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

With no annotations provided, the description carries full burden and effectively discloses key behaviors: it's a read operation (implied by 'Fetch'), returns structured data (UserSummary object), and emphasizes efficiency ('quick overview'). However, it lacks details on error handling or rate limits.

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?

Well-structured with clear sections (Args, Returns, Use cases) and front-loaded purpose, but slightly verbose in listing return fields and use cases. Every sentence adds value, though some redundancy exists with the schema.

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 moderate complexity, no annotations, but a detailed output schema (implied by Returns section), the description provides complete context: purpose, usage, parameters, and return structure, compensating adequately for the lack of annotations.

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 the schema already fully documents the single parameter. The description repeats the parameter info but adds no additional semantic context beyond what's in the schema, meeting the baseline for high coverage.

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 specific action ('Fetch a comprehensive summary') and resource ('user's profile'), distinguishing it from siblings like get_user_badges or get_user_topics by emphasizing a holistic overview rather than specific components.

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?

It explicitly states when to use this tool ('to evaluate credibility, find contributions, understand participation') and when not to use it ('without fetching individual post histories'), providing clear alternatives and context for selection.

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

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 operation (implied by 'fetch'), returns paginated results, and specifies the exact structure of returned objects. It also explains pagination mechanics ('Paginate by incrementing the page parameter'), which is valuable behavioral context not captured elsewhere.

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 well-structured with clear sections (purpose, args, returns, use cases, pagination guidance). Every sentence adds value: the opening statement defines purpose, the args section clarifies parameters, the returns section details output structure, and the use cases provide practical guidance. No wasted words.

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 that there's an output schema (implied by 'Returns a list of topic objects'), the description provides excellent context. It covers purpose, parameters, return structure, use cases, and pagination behavior. For a read-only tool with good schema coverage, this description provides complete contextual understanding.

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 the schema already fully documents both parameters. The description adds minimal value beyond the schema - it repeats the parameter descriptions verbatim and adds pagination guidance. This meets the baseline expectation when schema coverage is complete.

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 specific action ('Fetch topics created by a specific user') and distinguishes it from sibling tools like get_user_replies or get_user_summary by focusing exclusively on topics initiated by the user. The verb 'fetch' combined with the resource 'topics created by a specific user' provides precise intent.

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 explicitly provides three use cases ('See what discussions a user has initiated', 'Find expert users in specific areas', 'Research a user's areas of interest'), giving clear context for when to use this tool. It also distinguishes from alternatives by focusing on user-created topics rather than replies or other user data available in sibling tools.

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

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 mentions pagination (via the offset parameter) and describes the return format ('dictionary with user badge information'), which adds useful context beyond the input schema. However, it doesn't disclose important behavioral aspects like rate limits, authentication requirements, error conditions, or what specific fields the dictionary contains.

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 well-structured with purpose statement, parameter documentation, return information, and usage guidance in four clear sections. It's appropriately sized for a tool with 2 parameters. The only minor improvement would be integrating the usage guidance more seamlessly rather than as a separate sentence.

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 moderate complexity (2 parameters, list operation), 100% schema coverage, and the presence of an output schema (implied by 'Returns a dictionary'), the description provides adequate context. It covers purpose, parameters, returns, and usage guidance. The main gap is lack of behavioral details that would be important for a production agent (authentication, rate limits, error handling).

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 the schema already fully documents both parameters. The description repeats the parameter descriptions verbatim from the schema ('badge_id: The numeric badge ID', 'offset: Pagination offset') without adding additional semantic context, format requirements, or examples. This meets the baseline expectation when schema coverage is complete.

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 specific action ('List all users who have earned a specific badge') and distinguishes it from sibling tools like 'get_user_badges' (which gets badges for a user) or 'get_user_summary' (which provides general user info). It explicitly identifies the resource (users with a badge) and the filtering criteria (badge_id).

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 provides clear context for when to use this tool ('Use to find community members with specific achievements or recognition levels'), which helps differentiate it from general user listing tools. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools for different scenarios.

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

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It excellently describes key behavioral traits: the session remains authenticated for subsequent calls, credentials are not persisted, it returns a structured LoginResult with specific fields, and it handles optional 2FA. This provides comprehensive behavioral context beyond basic functionality.

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 well-structured with clear sections (purpose, parameters, usage guidelines, return values, behavioral notes). While slightly longer than minimal, every sentence serves a purpose - no redundant information. The front-loading of the core purpose is effective.

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 that this is an authentication tool with no annotations but with comprehensive output schema (implied by the Returns section), the description provides complete context. It covers authentication scope, session persistence, security considerations, return structure, and usage guidelines - everything needed for an agent to understand and use this tool correctly.

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 the schema already documents all parameters thoroughly. The description repeats the parameter information in the Args section but doesn't add significant semantic value beyond what's in the schema. This meets the baseline expectation when schema coverage is complete.

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 specific action ('Authenticate with USCardForum credentials') and identifies the resource (forum authentication). It distinguishes this tool from all sibling tools which are various read operations, making the purpose unambiguous and well-differentiated.

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 provides explicit guidance on when to use this tool ('Only use this if you need authenticated features like: - Reading notifications - Bookmarking posts - Subscribing to topics') and when not to use it ('Most read operations work without authentication'). It effectively contrasts with sibling tools that don't require authentication.

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

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 thoroughly describes the tool's behavior: it explains the return format (SearchResult object with posts, topics, users, and metadata), pagination handling ('If more results exist, increment page parameter'), and search capabilities (including operators and sorting options), covering aspects like output structure and operational constraints.

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 well-structured with clear sections (Args, Returns, Example queries, Pagination) and is appropriately sized for a search tool with multiple parameters and complex functionality. However, it could be slightly more concise by integrating some details (e.g., merging operator examples into the query description) without losing clarity.

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 complexity (3 parameters, no annotations, but with an output schema), the description is complete. It covers purpose, usage, parameters with examples, return values (leveraging the output schema for structure), and behavioral aspects like pagination, ensuring the agent has all necessary information to use the tool effectively.

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 adds significant value beyond the input schema, which has 100% coverage but minimal detail. It elaborates on the query parameter with specific operator examples and syntax, details the order parameter with all sort options and their meanings, and clarifies pagination usage for the page parameter, providing practical guidance not present in the schema descriptions.

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 purpose: 'Search USCardForum for topics and posts matching a query.' It specifies the verb ('search'), resource ('USCardForum'), and scope ('topics and posts'), distinguishing it from sibling tools like get_hot_topics or get_new_topics that retrieve predefined lists rather than performing custom searches.

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 provides clear context for when to use this tool (searching with queries and operators) and includes example queries. However, it does not explicitly state when not to use it or name specific alternatives among the sibling tools, such as get_topic_info for detailed topic information instead of search results.

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

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

With no annotations provided, the description carries the full burden and effectively discloses key behavioral traits: it specifies authentication requirements ('REQUIRES AUTHENTICATION'), describes the action's effect (setting notification levels), and outlines the return structure. It does not mention rate limits or error handling, but covers essential operational 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 well-structured with clear sections (purpose, args, returns, use cases), front-loaded key information, and avoids redundancy. It could be slightly more concise by integrating the 'Use to' examples into the initial description, but overall it's efficient and readable.

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 complexity (authentication, parameter semantics, mutation), no annotations, and an output schema, the description is complete: it covers purpose, usage, parameters, prerequisites, return values, and examples, providing all necessary context for an agent to invoke it correctly without relying on structured fields.

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 the baseline is 3. The description adds value by explaining the semantic meaning of the 'level' parameter with detailed enum-like descriptions (e.g., '0: Muted (no notifications)'), which clarifies usage beyond the schema's basic labels, though it doesn't add new information for 'topic_id'.

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 specific action ('Set your notification level for a topic') with the resource ('topic') and distinguishes it from siblings by focusing on subscription management rather than retrieval or other operations like 'bookmark_post' or 'get_topic_info'.

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?

It provides explicit guidance on when to use the tool (e.g., 'Watch topics for all updates', 'Mute noisy topics', 'Track topics you've contributed to'), includes prerequisites ('Must call login() first'), and distinguishes from alternatives by its unique subscription functionality not covered by other tools.

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