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 successfully communicates authentication requirements, the mutation nature of the operation (bookmark creation), and the return format (Bookmark object). However, it doesn't mention potential side effects like duplicate bookmarks, error conditions, 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?

The description is well-structured with purpose statement, authentication requirement, parameter details, prerequisite, return value, and usage reinforcement. While slightly longer than minimal, every sentence adds value. The parameter explanations could be more concise.

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 with output schema (implied by 'Returns a Bookmark object'), the description is mostly complete. It covers authentication, parameters, prerequisites, and return format. However, it lacks information about error conditions, idempotency, or what happens when bookmarking already-bookmarked posts.

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. The description adds significant value by explaining the auto_delete_preference parameter's enum values (0-3 with meanings) and clarifying that post_id is numeric. However, it doesn't provide additional context for reminder_type beyond what's in 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 specific action ('Bookmark a post') and resource ('post for later reference'), distinguishing it from sibling tools which are primarily get/read operations. The final sentence reinforces the purpose by stating 'Use to save interesting posts for later reference.'

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 ('Must call login() first') and provides clear prerequisites (authentication requirement). It also distinguishes from sibling tools by being the only bookmarking/mutation tool among primarily read-only operations.

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 the automatic pagination mechanism, provides safety guidance about response size limits for large topics, describes how parameters interact (start_post_number, end_post_number, max_posts), and references the return structure. The only minor gap is not explicitly mentioning whether this is a read-only operation, though 'fetch' implies it.

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, parameter explanations, important notes, use cases, return information, and pro tip. While comprehensive, some redundancy exists (parameter descriptions partially repeat schema info). Every sentence adds value, but it could be slightly more concise by eliminating schema 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 (automatic pagination, multiple interacting parameters) and the presence of an output schema (mentioned in 'Returns the same Post structure as get_topic_posts'), the description is complete. It covers purpose, usage guidelines, parameter semantics, behavioral traits, and references sibling tools appropriately. No significant gaps remain 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?

Schema description coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by explaining parameter interactions and practical usage: it shows how start_post_number, end_post_number, and max_posts work together, provides default behavior explanations, and gives concrete examples of parameter combinations in the use cases section. This goes well beyond what the schema descriptions provide.

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: 'Fetch all posts from a topic with automatic pagination.' It specifies the verb ('fetch'), resource ('posts from a topic'), and key behavioral trait ('automatic pagination'). It distinguishes from sibling 'get_topic_posts' by emphasizing comprehensive fetching with pagination handling.

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. It includes an 'IMPORTANT' section advising to use max_posts for large topics, mentions using 'get_topic_info first to check post_count before deciding whether to fetch all or paginate manually,' and gives four concrete use cases with parameter examples. It clearly differentiates from 'get_topic_posts' by handling pagination automatically.

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 by specifying the return type (CategoryMap object), the scope (all categories including main and subcategories), and practical applications. It does not mention potential limitations like rate limits or authentication needs, but covers core functionality adequately.

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 and return value, followed by explanatory context and use cases. 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 (0 parameters, no annotations, but with an output schema), the description is complete. It explains what the tool does, what it returns, and how to use the output, compensating for the lack of annotations. The presence of an output schema means the description does not need to detail return values, and it adequately covers all relevant aspects.

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 input schema has 0 parameters with 100% coverage, so the baseline is 4. The description adds no parameter-specific information, which is appropriate since no parameters exist, and instead focuses on output semantics and usage context.

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 verb ('Get') and resource ('mapping of all forum categories'), distinguishing it from sibling tools like get_topic_info or get_user_summary that focus on different resources. It explicitly defines what the tool returns (CategoryMap object) and its purpose (organizing topics by subject area).

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 by listing specific use cases (filter search results, understand topic sections, navigate to areas of interest). However, it does not explicitly state when NOT to use it or name alternatives among sibling tools, such as using get_topic_info for topic-specific details instead.

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. It discloses that the tool returns session information and authentication status, which is useful behavioral context. However, it doesn't mention potential errors, rate limits, or other operational traits beyond the basic return structure.

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 front-loaded with the core purpose, followed by details on the return object and usage guidance. Every sentence adds value without redundancy, making it efficiently structured and appropriately sized for the tool's simplicity.

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, output schema exists), the description is mostly complete. It explains what the tool does and what it returns, but lacks details on error handling or edge cases, which holds it back from a perfect score.

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, and schema description coverage is 100%. The description doesn't need to add parameter semantics, so it meets the baseline of 4 for zero-parameter tools, as it appropriately focuses on output and 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 ('Get information about the current session') with a specific verb and resource. It distinguishes itself from siblings by focusing on session/authentication status rather than user data, topics, or posts, though it doesn't explicitly name 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 clear context for usage ('Use to verify authentication status'), which implicitly guides when to use it. 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 and does well by explaining ranking criteria ('engagement metrics like recent replies, views, and likes'), pagination behavior, and return format. It also includes example response interpretation for behavioral context, though it could mention rate limits or authentication needs.

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, usage guidelines, args, returns, examples) and front-loaded key information. It could be slightly more concise by avoiding redundancy in the Args section, but overall it's efficient with zero 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 moderate complexity, no annotations, and the presence of an output schema, the description is complete. It covers purpose, usage, parameters, return values, and behavioral interpretation, providing sufficient context for an AI 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema by restating the parameter in the Args section ('page: Page number for pagination (0-indexed)') but doesn't provide additional semantics like format details or usage nuances.

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 ('currently trending/hot topics from USCardForum'), distinguishing it from siblings like get_new_topics or get_top_topics by specifying 'most actively discussed topics right now' based on engagement 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 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 guide when to use this tool versus alternatives like get_new_topics or get_top_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 the full burden and does well by disclosing key behaviors: it's a read operation (implied by 'fetch'), returns sorted results (newest first), explains that results may have fewer replies, and mentions pagination. It doesn't cover rate limits or authentication needs, but provides substantial 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?

Well-structured with purpose first, then usage guidelines, parameters, return values, and a tip. Some redundancy exists (pagination info appears in both description and schema), but overall it's appropriately sized and front-loaded with essential 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 moderate complexity (single optional parameter), no annotations, but with an output schema that documents return values, the description provides excellent contextual completeness. It covers purpose, usage, behavior, parameters, and includes helpful tips 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 fully documents the single parameter. The description repeats the pagination information in the Args section but adds no additional semantic context beyond what's in the schema, meeting the baseline expectation.

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 resources ('latest/newest topics from USCardForum'), distinguishing it from siblings like get_hot_topics or get_top_topics by emphasizing recency over popularity or ranking.

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 provides usage scenarios ('Use this to:') with three specific examples (find deals, see fresh questions, discover emerging discussions) and includes a tip about high view counts, offering clear guidance on when to use this tool versus 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 requirement ('REQUIRES AUTHENTICATION'), pagination behavior via limit parameter, and filtering capabilities. It also describes the return format in detail. Could improve by mentioning rate limits or any destructive effects (though likely none for a fetch 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?

Well-structured with clear sections: purpose statement, parameter documentation, prerequisite, return format, and use cases. Could be slightly more concise by integrating parameter details more efficiently, but overall information density is good with minimal 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 has an output schema (implied by the detailed return format description) and 100% schema coverage, the description provides excellent contextual completeness. It covers authentication requirements, parameter usage, return format, and specific use cases, making it fully sufficient for an agent to understand and use 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 fully documents all three parameters. The description repeats the parameter information but doesn't add significant semantic context beyond what's in the schema. 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 verb 'fetch' and resource 'notifications', distinguishing it from sibling tools like get_user_actions or get_user_replies which focus on different data types. It specifies retrieving notifications specifically, not other user 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?

Explicitly states 'Must call login() first' for authentication prerequisite and provides clear use cases: 'Check for new replies to your posts', 'See mentions and likes', 'Track topic updates you're watching'. This gives concrete guidance on when to use this tool versus 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?

No annotations are provided, so the description carries the full burden. It discloses behavioral traits such as the tool's role in pagination planning, decision-making for fetching posts, and handling of large topics with specific thresholds. However, it lacks details on error handling, rate limits, or authentication needs, which are common for API tools.

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, Use this FIRST, Returns, Strategy), but it could be more concise by avoiding repetition (e.g., the topic_id explanation is duplicated in Args and schema). Most sentences earn their place by adding useful context, though some trimming is possible.

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, no annotations, but with an output schema), the description is complete. It explains the purpose, usage, parameters, return values (with a TopicInfo object detailed), and strategic advice, compensating for the lack of annotations. The output schema means return values don't need further 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 baseline is 3. The description adds value by explaining the parameter's origin ('from URLs like /t/slug/12345') and its purpose in the context of the tool's usage, but it doesn't provide additional syntax or format details beyond what the schema already covers.

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 ('Get metadata') and resource ('about a specific topic'), distinguishing it from siblings like 'get_topic_posts' or 'get_all_topic_posts' by emphasizing it fetches metadata without posts. It explicitly differentiates from alternatives by stating 'without fetching all 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') and includes detailed strategies for different scenarios (e.g., 'Safe to fetch all at once' for <50 posts). It contrasts with siblings by implying this is a preliminary step before fetching posts, offering clear alternatives like pagination or batching.

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 specifies the batch size ('~20 posts per call'), describes the return format in detail, explains pagination behavior, and clarifies what happens when no posts are returned. It doesn't mention rate limits or authentication requirements, which keeps it from a perfect score.

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, usage example) and front-loaded with the core functionality. While comprehensive, some information (like the detailed return fields) could be more concise, but every sentence serves a clear 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 the tool's moderate complexity, no annotations, but with a detailed output schema implied by the return description, the description is complete. It covers purpose, parameters, behavior, return format, and usage patterns, providing everything needed 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.

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 explanations in the 'Args' section but adds minimal value beyond what's in the schema. The baseline of 3 is appropriate when the 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 a batch of posts from a topic') with the resource ('topic') and distinguishes it from siblings like 'get_all_topic_posts' by specifying pagination ('starting at a specific position'). The first sentence provides a complete verb+resource+scope statement.

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 step-by-step instructions. It distinguishes from 'get_all_topic_posts' by emphasizing the batch/paginated nature versus presumably fetching all posts at once.

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: the tool returns sorted results ('sorted by engagement score'), supports pagination ('Page number for pagination'), and returns structured data ('Returns TopicSummary objects'). However, it doesn't mention potential limitations like rate limits, authentication requirements, or data freshness.

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, Use this to, Returns, Example), uses bullet points efficiently, and every sentence adds value without redundancy. It's appropriately sized for a tool with 2 parameters and good behavioral context.

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, 100% schema coverage, output schema exists), the description is complete. It covers purpose, usage guidelines, parameter semantics, return values, and includes examples. The existence of an output schema means the description doesn't need to detail return value structure, which it appropriately avoids.

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 significant value by explaining the semantic meaning of period options (e.g., 'daily': Top topics from today, 'weekly': Top topics this week) and providing context for the page parameter ('Use page=1 to get more topics'), which goes beyond the schema's technical 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 specific verb ('Fetch') and resource ('top-performing topics'), and distinguishes it from siblings like 'get_hot_topics' or 'get_new_topics' by specifying ranking based on performance over time periods rather than 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 description explicitly provides usage scenarios ('Find the most valuable discussions', 'Research historically important threads', 'Identify evergreen popular content') and includes an example that distinguishes when to use different period values ('Use "yearly" to find the most impactful discussions, or "daily" to see what's trending today'), offering clear guidance on when to use this tool versus 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a list of UserAction objects and mentions pagination via offset, which adds useful context. However, it lacks details on permissions, rate limits, error handling, or the structure of UserAction objects, leaving behavioral 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 a clear purpose statement, parameter details in an 'Args' section, return information, and usage guidelines. It's front-loaded and efficient, though the bulleted list for filter values adds some length but is justified for clarity. Every sentence earns its place without 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?

Given the tool's moderate complexity (3 parameters, no annotations, but with an output schema), the description is fairly complete. It covers purpose, parameters, returns, and usage guidelines. The output schema likely defines UserAction objects, so the description doesn't need to detail return values. However, it could improve by addressing behavioral aspects like authentication or limits.

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 adds minimal value beyond the schema by listing common filter values in a bulleted format, but it doesn't provide additional semantics like edge cases or usage examples. This meets the baseline for high schema 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 user's activity feed') and resource ('user'), distinguishing it from siblings like get_user_replies or get_user_topics by emphasizing 'detailed activity analysis beyond just replies.' It provides a verb+resource+scope combination that is precise and 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 explicitly provides when to use this tool ('for detailed activity analysis beyond just replies') and when not to ('for most cases, get_user_replies or get_user_topics are simpler'), naming specific alternatives. This gives clear guidance on tool selection relative to siblings.

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 describes the return structure, but lacks details on behavioral traits like error handling, rate limits, authentication needs, or whether it's idempotent. The description adds some context about badge types but misses key 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 appropriately sized and front-loaded with the core purpose. However, the 'Args' section repeats schema info unnecessarily, and the 'Badges indicate' and 'Use to assess' sections, while helpful, could be more integrated. It's efficient but has minor structural 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?

Given the tool's low complexity (2 parameters, 1 required), 100% schema coverage, and the presence of an output schema (implied by 'Returns a UserBadges object'), the description is mostly complete. It explains the purpose, usage context, and return structure, though it lacks behavioral details like error cases or performance considerations.

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 fully. The description repeats the parameter info in the 'Args' section without adding meaning beyond the schema (e.g., explaining why grouping matters or format details). This meets the baseline of 3 when schema coverage is high.

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. It distinguishes from siblings like 'list_users_with_badge' (which lists users with a badge) by focusing on badges for a specific user, and from 'get_user_summary' by targeting badges specifically rather than general user 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 provides clear context for when to use this tool: 'to assess user experience and trustworthiness' based on badges indicating participation, community recognition, and special achievements. However, it does not explicitly state when not to use it or name alternatives (e.g., 'get_user_summary' for broader user info), which prevents 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions pagination and the return format, which adds useful context beyond basic functionality. However, it lacks details on rate limits, authentication needs, or error handling, leaving gaps for a mutation-free 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 front-loaded with the core purpose, followed by parameter and return details. The final sentence about follower count adds minor value but doesn't detract significantly, keeping it efficient overall.

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 the presence of an output schema, the description is reasonably complete. It covers purpose, parameters, and returns adequately, though it could benefit from more behavioral context like error cases or pagination defaults.

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 thoroughly. The description repeats the parameter info without adding meaningful context like format constraints or usage examples, earning the baseline score for adequate but redundant 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 tool's purpose with a specific verb ('fetch') and resource ('list of users following a specific user'), making it easy to understand what it does. However, it doesn't explicitly differentiate from sibling tools like 'get_user_following' or 'get_user_summary', which prevents a perfect score.

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. It doesn't mention sibling tools like 'get_user_following' (which might fetch users a person follows) or 'get_user_summary' (which might include follower info), leaving the agent without context for tool 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 full burden for behavioral disclosure. It reveals pagination behavior through the 'page' parameter documentation and describes the return format (FollowList object structure). However, it doesn't mention rate limits, authentication requirements, error conditions, or whether this is a read-only operation (though 'fetch' implies reading).

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). It's appropriately sized at 6 sentences, though the 'Args:' section somewhat duplicates schema information. Most sentences earn their place by providing distinct 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 has an output schema (implied by 'Returns a FollowList object'), the description doesn't need to fully explain return values. It provides adequate context for this read-only data retrieval tool, though it could benefit from mentioning authentication requirements or rate limits given no annotations are provided.

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 in the 'Args:' section but doesn't add meaningful semantic context beyond what's in the schema (e.g., format expectations for username, pagination strategy details). 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 'Fetch the list of users that a user follows' - a specific verb+resource combination. It distinguishes itself from sibling tools like get_user_followers (which would fetch followers rather than following), though it doesn't explicitly mention this distinction in the description itself.

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 about when to use this tool ('Discover influential users', 'Find related experts', 'Map social connections'). However, it doesn't explicitly state when NOT to use it or mention specific alternatives among the sibling tools (like get_user_followers for the reverse relationship).

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 (implying read-only behavior) and mentions pagination via the 'offset' parameter, which adds useful context. However, it doesn't cover other behavioral aspects like rate limits, authentication needs, error conditions, or what 'UserReactions object' contains beyond 'reaction data'. The description adds some value but leaves 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 appropriately sized and front-loaded: the first sentence states the purpose clearly, followed by parameter and return value notes, then usage guidance. Each sentence adds value (e.g., explaining the purpose of fetching reactions). It could be slightly more structured (e.g., separating sections), but it's efficient with zero 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 moderate complexity (2 parameters, read-only operation), the description is reasonably complete. It covers purpose, parameters, returns, and usage context. Since an output schema exists (implied by 'Returns a UserReactions object'), the description doesn't need to detail return values. However, with no annotations, it could better address behavioral aspects like error handling or data scope.

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%, with both parameters ('username' and 'offset') well-documented in the schema. The description adds minimal semantics: it restates 'username' as 'The user's handle' and 'offset' as 'Pagination offset', which doesn't provide additional meaning beyond the schema. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.

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: 'Fetch a user's post reactions (likes, etc.)'. It specifies the verb (fetch) and resource (user's post reactions), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_user_actions' or 'get_user_replies', which might also involve user activity 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 provides some usage context: 'Use to see what content a user has reacted to, which can indicate their interests and values.' This implies when to use the tool (for analyzing user interests via reactions), but it doesn't explicitly state when not to use it or name alternatives among siblings (e.g., 'get_user_actions' for broader activity). The guidance is helpful but not 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 behaviors: it describes pagination mechanics ('Paginate with offset in increments of 30'), specifies the return format (list of UserAction objects with fields), and implies read-only nature through 'Fetch'. It doesn't mention rate limits or auth needs, but covers essential operational details.

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, args, returns, usage, pagination) and no wasted sentences. Each part adds value, such as explaining the return structure and providing usage examples, making it easy to scan and understand.

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 'Returns a list of UserAction objects'), the description is complete enough. It covers purpose, parameters, return values, usage scenarios, and pagination behavior, leaving no critical gaps for an AI agent to invoke it 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 both parameters fully. The description repeats parameter info (e.g., 'offset: Pagination offset (0, 30, 60, ...)') without adding significant meaning beyond the schema, such as explaining why increments of 30 are used or constraints on username format. Baseline 3 is appropriate as the 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 ('replies/posts made by a user in other topics'), distinguishing it from siblings like get_user_topics (user's own topics) and get_user_actions (broader actions). It precisely identifies what is being retrieved and from where.

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 context with 'Use this to:' examples (e.g., 'See a user's contributions across topics'), which helps understand when to apply this tool. However, it doesn't explicitly state when not to use it or name specific alternatives among siblings, such as get_user_actions, which might overlap in functionality.

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 full burden. It discloses that the tool returns a comprehensive summary object with specific fields, but doesn't mention behavioral aspects like rate limits, authentication requirements, error conditions, or whether this is a cached/real-time view.

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. Some sentences could be more concise (e.g., 'The summary provides a quick overview without fetching individual post histories' could be tightened), but overall 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 has an output schema (Returns section details the structure) and 100% schema coverage for the single parameter, the description provides adequate context. It explains the tool's purpose, usage scenarios, and what information it provides, though could benefit from mentioning any limitations or prerequisites.

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 parameter's case-insensitive nature and providing context about what 'username' represents ('user's handle'), elevating it above the minimum viable level.

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 sibling tools like get_user_badges or get_user_topics by emphasizing it provides 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?

Explicitly states when to use this tool ('Evaluate a user's credibility and experience', 'Find their most valuable contributions', 'Understand their participation level') and when not to use it ('without fetching individual post histories'), providing clear alternatives to more granular 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 full burden. It discloses the pagination behavior ('Paginate by incrementing the page parameter') and the return format (list of topic objects with specific fields), but doesn't mention rate limits, authentication requirements, or error conditions that might be relevant for a user query 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 statement, args explanation, returns format, and usage guidelines. It's appropriately sized but could be slightly more concise by avoiding repetition of parameter descriptions already in 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 has an output schema (implied by 'Returns a list of topic objects'), the description doesn't need to explain return values in detail. It provides good context about usage scenarios and pagination behavior, though it could benefit from mentioning authentication requirements or error handling for a user query tool.

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 fully. The description repeats the parameter explanations but doesn't add meaningful semantics beyond what's in the schema (e.g., format constraints for username, pagination strategy details). 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 verb 'fetch' and resource 'topics created by a specific user', distinguishing it from siblings like get_user_replies or get_user_actions which focus on different user activities. It specifies the exact scope of what's being retrieved.

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 use cases: 'See what discussions a user has initiated', 'Find expert users in specific areas', and 'Research a user's areas of interest'. It also mentions pagination guidance, though it doesn't explicitly contrast with alternatives like get_user_replies.

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 'offset' and returns 'a dictionary with user badge information', which adds some context beyond the schema. However, it lacks details on permissions, rate limits, or what specific information the dictionary contains, leaving gaps 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 with the core purpose, followed by parameter details and usage guidelines. Every sentence earns its place: the first states the action, the second and third explain parameters, the fourth describes returns, and the fifth provides usage context, with 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 the tool's moderate complexity (2 parameters, no annotations, but with output schema), the description is mostly complete. It covers purpose, parameters, returns, and usage, but lacks behavioral details like permissions or rate limits. The presence of an output schema reduces the need to explain return values, but more context would enhance completeness for a tool with no 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 documents both parameters thoroughly. The description repeats 'badge_id: The numeric badge ID' and 'offset: Pagination offset (optional)', adding no extra meaning beyond the schema. This meets the baseline of 3 when schema coverage is high, but no additional value 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 verb 'List' and resource 'users who have earned a specific badge', making the purpose specific and actionable. It distinguishes from siblings like 'get_user_badges' (which gets badges for a user) by focusing on users for a badge, establishing 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 usage context: 'Use to find community members with specific achievements or recognition levels', which clearly indicates when this tool is appropriate. However, it does not specify when not to use it or name alternatives among siblings, such as 'get_user_badges' 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 full burden and delivers comprehensive behavioral information. It explains the session persistence ('The session remains authenticated for subsequent calls'), security handling ('Credentials are used only for this session and are not persisted'), return structure details, and authentication requirements including optional 2FA.

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 (purpose, args, usage guidelines, returns, behavioral notes). Every sentence adds value, though the bulleted lists could be slightly more concise. The information is front-loaded with the core authentication purpose stated immediately.

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 this is a critical authentication tool with no annotations but with output schema, the description provides complete context. It covers purpose, parameters, usage scenarios, return values, session behavior, and security considerations - everything needed to understand and use this 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining the optional nature of second_factor_token ('if you have 2FA enabled') and grouping all parameters under an 'Args:' section, which provides organizational value beyond the schema's individual parameter 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 specific action ('Authenticate with USCardForum credentials') and resource ('credentials'), distinguishing it from all sibling tools which are various read operations. It establishes this as the authentication entry point for the forum system.

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 when to use ('if you need authenticated features like: Reading notifications, Bookmarking posts, Subscribing to topics') and when not to use ('Most read operations work without authentication'). Provides clear alternatives by naming specific sibling tools that require authentication versus those that don't.

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 and does so effectively. It explains that the tool returns a SearchResult object with detailed components (posts, topics, users, metadata), describes pagination behavior ('If more results exist, increment page parameter'), and outlines the default sort order ('relevance'). It does not cover aspects like rate limits or authentication needs, 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?

The description is well-structured and front-loaded, starting with a clear purpose statement, followed by organized sections for arguments, returns, examples, and pagination. Every sentence adds value, such as the detailed query examples and pagination instructions, with no redundant or unnecessary information, 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.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (search functionality with multiple parameters and operators), the description is complete. It fully explains the input parameters with examples, describes the output structure in detail (SearchResult object with nested components), and includes practical usage guidance. The presence of an output schema reduces the need to explain return values, but the description still adds valuable context, making it comprehensive for agent use.

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 baseline is 3, but the description adds significant value beyond the schema. It elaborates on the 'query' parameter with detailed examples of Discourse operators (e.g., 'in:title', '@username'), provides a comprehensive list of 'order' options with explanations, and includes example queries that demonstrate parameter usage in context, enhancing understanding beyond the schema's basic 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 with a specific verb ('Search') and resource ('USCardForum for topics and posts'), distinguishing it from sibling tools like 'get_topic_info' or 'get_hot_topics' which retrieve specific content rather than performing searches. It explicitly identifies what is being searched (topics and posts) and how (matching a query).

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 a query) and includes example queries that illustrate practical applications. However, it does not explicitly state when not to use it or name alternatives among sibling tools, such as using 'get_hot_topics' for trending content without a specific query.

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 authentication requirement ('REQUIRES AUTHENTICATION'), the mutation nature of setting notification levels, and the return structure. However, it lacks details on error conditions, rate limits, or side effects like whether this affects other users.

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, followed by organized sections for arguments, prerequisites, returns, and usage examples. Every sentence adds value without redundancy, 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.

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, mutation operation), no annotations, but with an output schema, the description is complete. It covers authentication needs, parameter semantics, return values, and usage scenarios, providing sufficient context for an agent to invoke it correctly without relying on structured fields alone.

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 baseline is 3. The description adds value by explaining the semantic meaning of 'level' values with clear examples (0=muted, 1=normal, etc.) and use cases, which enhances understanding beyond the schema's technical definitions. It doesn't add much for 'topic_id' but compensates well for 'level'.

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') and resource ('topic'), distinguishing it from siblings like 'bookmark_post' or 'get_topic_info' which perform different operations on topics. It explicitly defines the verb and target, making 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 provides explicit guidance on when to use this tool ('Use to: Watch topics for all updates, Mute noisy topics, Track topics you've contributed to') and includes prerequisites ('Must call login() first'). It also distinguishes usage scenarios by notification levels, though it doesn't explicitly name alternatives among siblings.

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