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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description explains what the tool returns (a complete markdown guidance document) and its role in ensuring correct workflows, tool sequencing, dataset compatibility checks, and code generation. This adds substantial behavioral context without contradicting 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 lengthy but well-structured with clear sections, bullet points, and examples. It is front-loaded with the critical 'IMPORTANT' notice. Some redundancy exists (e.g., repeated emphasis on calling first across multiple sections), but each part adds value for such an important prerequisite tool.

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?

The description fully covers the tool's role, triggers, expected content, return type, and example workflows. Given the output schema exists and the tool has no parameters, this description provides all necessary context for an agent to use it correctly as the initial step in Teal-related interactions.

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 no parameters, so the baseline is 4. The description correctly omits parameter details and instead focuses on the tool's output and usage, which is appropriate for a zero-parameter meta-guidance tool.

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 comprehensive guidance for assisting users with Teal application development.' It uses a specific verb and resource, and distinguishes itself from sibling tools by positioning itself as the mandatory first step for any Teal-related task.

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 says when to use the tool ('MUST be called FIRST whenever...') with a detailed list of triggering scenarios, and provides example user requests with corresponding first actions. It also instructs 'Always retrieve this guidance at the start of any Teal-related conversation', making usage guidance unambiguous.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavior beyond annotations by detailing what the tool does (compares requirements, returns compatibility report) and how it handles flexible dataset types. It does not contradict 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 lengthy but well-structured with clear sections (Args, Returns, Flexible Dataset Type Matching, Examples, Recommended Workflow). It front-loads the core purpose and then provides necessary detail. Some redundancy exists (e.g., repeated mention of verification), but overall every section serves a 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 and schema with 0% property descriptions, the description delivers complete context: parameter details, return content, flexible matching rules, examples, and a recommended workflow. The presence of an output schema reduces the need to explain return format, but the description still covers it, ensuring the agent can 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?

Input schema coverage is 0%, so the description fully compensates. It explicitly explains module_name, available_datasets with an example list, and response_format with allowed values and default. Examples further illustrate parameter usage, making parameter semantics crystal clear.

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 a specific verb+resource: 'Check if required datasets are available for a specific module.' It distinguishes itself from sibling tools by focusing on validating module requirements rather than listing or discovering datasets. The first sentence alone captures the purpose unambiguously.

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 workflow guidance: 'Recommended Workflow' includes steps to call discover_datasets, get_dataset_info, then this tool. It also advises using get_dataset_info before checking compatibility, clarifying the proper sequence and relationship to alternatives. This is rare and valuable.

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?

Description adds substantial behavioral context beyond annotations: it runs the app using shiny::runApp(), detects startup errors only, terminates the process after confirmation or error, and details timeout behavior. None of this contradicts the readOnlyHint and idempotentHint annotations, and it meaningfully extends them.

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 (summary, Args, Returns, Error Types, Examples, Note) and front-loaded with the core purpose. Every section contributes valuable information—no redundant or filler content—making it appropriately detailed without being bloated.

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, the description is remarkably complete. It includes parameter details, output JSON structure, a comprehensive list of error types, examples for typical use cases, and a note about non-interactive behavior. It fully equips an agent to invoke the tool correctly and interpret results, despite the presence of an output schema.

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 provides only type and default, with 0% description coverage. The description compensates fully by explaining each parameter's meaning (e.g., app_path 'Path to the Shiny app directory', timeout_seconds 'Maximum time in seconds' with range 1-120) and offering concrete usage examples. This goes well 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's first sentence 'Check if a Shiny app starts without errors' clearly identifies the action and resource. It further specifies the mechanism (shiny::runApp()) and differentiates from siblings by focusing on startup validation, a unique concern among the listed tealflow 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 states it is 'useful for validating that a Teal application has been correctly configured before attempting to run it interactively,' providing clear context. It also notes the tool does not launch an interactive session and terminates after startup, but does not explicitly name alternative tools or exclusions, so it misses the top 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable operational context: absolute path requirement (and why relative paths fail), case-insensitive extension handling, normalization to uppercase, and common errors. It also explains the output contents, giving full transparency beyond the 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 with sections (Args, Returns, Examples, Common Errors, Note) and front-loads the purpose. It is verbose, but every section adds necessary information given the 0% schema coverage. Some minor redundancy exists (e.g., filename handling is mentioned twice), so it loses one point.

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 tool with 4 parameters, no schema descriptions, but rich annotations and an output schema, the description is complete. It covers purpose, input requirements, parameter semantics, examples, error conditions, filename edge cases, and return contents. There are no significant gaps.

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 0%, so the description must compensate fully. It does: data_directory is explained as an absolute path with examples, file_formats is defined as a list with null default, pattern is given its default 'AD*', and response_format is explained with 'markdown' vs 'json'. This adds rich meaning beyond the bare 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 opens with 'Discover ADaM datasets in a directory,' a specific verb+resource+scope statement. It further explains that it scans, identifies dataset names, and collects metadata, clearly distinguishing it from sibling tools like list_datasets by emphasizing filename normalization and metadata collection.

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: it is used for discovering ADaM datasets, requires an absolute path, and handles complex filenames. It warns against relative paths and gives examples. However, it does not explicitly name alternative tools or state when to choose this tool over siblings, so it falls short of a 5.

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?

Despite strong annotations (readOnly, idempotent), the description adds substantial behavioral context: it clarifies the tool only generates code (it does not load data), mandates absolute paths, sorts datasets alphabetically, supports only Rds/csv formats, and details the generated code structure including join keys configuration. This goes well beyond what annotations convey.

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 long but well-structured with clear sections (IMPORTANT, Path Handling, Args, Returns, Generated Code Structure, Workflow Integration, Examples, Note). Every section serves a purpose, though some redundancy exists (e.g., path handling repeated). It remains appropriately sized for a complex code-generation tool.

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?

The description covers the full invocation context: prerequisites, parameter semantics, return formats (markdown/json), generated code structure, and integration steps. With an output schema present, it doesn't need to detail every field, but it provides enough for correct selection and use. The sibling tool relationships are clarified via workflow.

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% description coverage, but the description fully compensates. It defines each parameter in detail: 'datasets' list contains name, path, format, is_standard_adam; 'project_directory' controls relative vs absolute paths; 'response_format' changes the return structure. This adds complete meaning beyond the bare 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 opens with a specific verb and resource: 'Generate R code for loading discovered datasets and creating a teal_data object.' This clearly distinguishes it from sibling tools like tealflow_generate_module_code, which focuses on module generation. The workflow integration section further clarifies its role in the discovery-to-app pipeline.

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 workflow integration: use tealflow_discover_datasets first, pass the datasets_found array, save generated code as data.R. It also states that it is 'designed to work seamlessly' with discovery output. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a 5.

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?

Annotations already indicate read-only and idempotent behavior, but the description adds context: it returns a string snippet, includes comments conditionally, and discloses that the 'parameters' argument is 'Not yet implemented'. It also warns that generated code uses standard dataset configuration and may need adjustment, which is valuable behavioral info beyond the 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 with clear sections (IMPORTANT, Args, Returns, Examples, Recommended workflow, Note), but it has some redundancy. The first two sentences both state that it generates R code, and the 'Includes' list partly repeats the return details. It is longer than necessary but mostly earns its place.

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?

The description is extremely complete for a code generation tool: it covers prerequisites, examples, input details, return value, workflow, and potential caveats. The presence of an output schema reduces the need to explain return values, but the description still provides sufficient context. No significant gaps remain.

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?

Despite the schema having 0% description coverage, the description fully compensates by explaining each parameter: module_name with examples, parameters as optional overrides with default None and note that it's not implemented, and include_comments with default True. It also describes the return value and includes, giving complete parameter semantics.

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 opens with 'Generate R code for adding a module to a Teal application,' which is a specific verb+resource statement. It further clarifies by listing module examples (tm_g_km, tm_t_coxreg) and explaining it produces ready-to-use R code, clearly distinguishing it from sibling tools like data loading or app template generation.

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 an explicit 'Recommended workflow' with 5 steps, instructing to use tealflow_get_dataset_info before generating code and tealflow_check_shiny_startup after. It also states to verify variable availability and data types, and notes when adjustments are needed. This gives clear when-to-use guidance and prerequisites, though it does not 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?

Annotations already declare the tool as read-only and idempotent. The description adds context about the template's contents (library imports, dataset configuration, etc.) and a note on modifying data sources. However, there is a slight ambiguity around the return type when 'json' format is requested, as it says 'Returns: str' but could imply a structured object.

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 Args, Returns, Usage, Examples, and Note sections. It is somewhat long due to the bullet list of template contents, but each item adds value for users understanding what the template includes. No redundant fluff.

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 simple getter tool, the description covers the purpose, what is returned, the template structure, usage workflow, examples, and important notes about data sources. The output schema exists, but the description goes beyond it by detailing the actual template components, making it fully complete for an agent to invoke 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 provides only a default with no description (0% coverage), but the description thoroughly explains the response_format parameter, including its two possible values ('markdown' and 'json') and defaults. Examples further clarify usage, fully compensating for the sparse 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 tool gets the Teal application template as a starting point for building apps. It specifies the exact resource and action, and the template contents are enumerated, making it distinct from sibling tools that focus on modules or datasets.

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?

An explicit 'Usage:' section provides step-by-step guidance, including using this tool first, then searching modules, generating code, and running the app. It clearly positions this tool as the initial step in a workflow, and examples illustrate parameter usage.

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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses critical behaviors: it requires an absolute path, reads only structure without loading the full dataset, uses pyreadr for RDS and pandas for CSV, and supports markdown or JSON response formats. It also lists common errors. This adds significant value beyond the annotations and is fully consistent with them.

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 long but well-structured with clear sections (IMPORTANT, Args, Returns, Column Type Mapping, Examples, Common Errors, Use Cases, Note). Each section adds useful information without redundancy. It is slightly verbose, but the structure helps an agent parse it efficiently, and every sentence serves a 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?

The description is complete for a tool of this complexity: it covers parameters, return formats, type mappings, examples, errors, use cases, and performance characteristics. Given that an output schema exists, the detailed return format explanation is extra helpful. The description leaves no significant gaps for an agent to correctly select and invoke this 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 0%, so the description carries the full burden for parameter explanations. It thoroughly explains file_path with absolute path requirement and examples, include_sample_values with its default and purpose, and response_format with 'markdown' vs 'json' options. It also includes examples of parameter combinations, fully compensating for the lack of 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 opens with a specific verb and resource: 'Get detailed information about a dataset file including columns, types, and row count.' It clearly focuses on inspecting a single dataset file, which distinguishes it from sibling tools like tealflow_list_datasets and tealflow_discover_datasets that handle dataset discovery and listing.

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 on when to use the tool: 'useful for understanding the contents of a dataset before using it in a Teal application.' The 'Use Cases' section further elaborates on specific scenarios. It does not explicitly mention alternatives or when not to use it, but the differentiation from siblings and the practical use cases provide solid guidance.

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?

The description adds extensive behavioral context beyond the annotations: error handling for missing modules, typo suggestions, graceful fallback for R help, and explanation of flexible dataset types. This complements the readOnly/idempotent hints without contradiction.

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 long but well-organized with sections for 'Includes', 'Flexible Dataset Types', 'Error Handling', and 'Examples'. Every section serves a purpose, though some redundancy exists (e.g., repeating parameters list).

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 (module details, dataset requirements, error handling, help docs), the description covers all key aspects: return content, dataset type explanations, error scenarios, and usage examples. It is self-sufficient for an agent to invoke 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?

With 0% schema description coverage, the description fully compensates by explaining module_name with concrete examples and response_format with values, defaults, and use cases. It adds meaning well beyond the bare schema definitions.

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 retrieves comprehensive details for a specific Teal module, including parameters and R help documentation. This distinguishes it from sibling tools like 'list_modules' or 'search_modules_by_analysis'.

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 says 'Use this after discovering a module to understand how to configure it properly', providing clear usage context. It doesn't name specific alternatives but the sibling tools and phrase 'after discovering' imply the appropriate workflow.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds value by stating the output is a string with dataset names, descriptions, usage info, and relationships, plus the CDISC standards adherence. It also discloses that it lists 'standard ADaM datasets,' which is a scope limitation. This goes beyond the annotations without contradicting them.

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 Args, Returns, Includes, and Examples sections. It is longer than necessary but each section earns its place by clarifying output and usage. The redundancy in the 'Includes' list (which largely mirrors Returns) is minor, but the format aids scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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

Given the tool's simplicity (one optional parameter, no required inputs) and the presence of an output schema, the description covers the essential aspects: purpose, parameter, return format, and content. It lacks error scenarios or specifics about dataset relationships, but for a read-only list tool, this is adequate. The main gap is sibling differentiation, which is already penalized in usage_guidelines.

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 for response_format is minimal (type and default), with 0% schema description coverage. The description fully compensates by explaining the parameter's purpose, valid values ('markdown' for human-readable, 'json' for machine-readable), and default behavior. This adds significant meaning 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 tool's function: 'List available clinical trial datasets in the project.' It identifies a specific verb ('List'), a specific resource ('datasets'), and provides context (clinical trial, ADaM standards). This effectively distinguishes it from siblings like list_modules and get_module_details, which focus on modules rather than datasets.

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 examples but lacks explicit guidance on when to use this tool versus alternatives. It does not mention sibling tools like tealflow_discover_datasets or tealflow_get_dataset_info, nor does it state when not to use this tool. Usage context is implied ('available for use with Teal clinical modules'), but there is no direct differentiation or exclusion.

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?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: describes return formats (markdown/JSON), explains flexible dataset requirement types (e.g., BDS_CONTINUOUS), and shows example output structures. No contradiction.

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 purpose, followed by clear sections (Args, Returns, Examples, Note). It is detailed but every sentence adds value, including concrete format examples that compensate for lack of schema 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?

The tool has 3 optional parameters, two output formats, and flexible dataset types. The description covers the listing function, filtering options, return structure, and links to a related tool for deeper details. Despite having an output schema, the description fully explains return values and usage, making it complete.

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?

Even though schema description coverage is 0%, the description's Args section thoroughly explains each parameter, defaults, and allowed values (package, category, response_format). It also includes examples that map parameters to actual 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 'List all available Teal modules with their descriptions and dataset requirements' — a specific verb + resource. It also distinguishes from the sibling tool tealflow_get_module_details by noting its role in listing vs. getting detailed requirements.

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?

Provides explicit usage context: filtering by package and category, with examples ('List all clinical modules', 'List graphics modules'). It also directs users to tealflow_get_module_details for more details, giving a clear alternative.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety traits are covered. The description adds behavioral detail about the search mechanism ('uses structured analysis type categories combined with text search'), the return structure ('List of matching modules organized by relevance'), and a caveat about flexible dataset types. This goes beyond annotations without contradicting them, though it doesn't specify edge cases such as no matches.

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 long but well-structured with clear sections (Args, Returns, Includes, Note, Categories, Examples). It front-loads the purpose and usage. Some content, like the predefined categories list and examples, is partly redundant, but it serves the agent by providing quick reference without requiring mental inference. Every section contributes to usability.

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 params, 1 required), the description is comprehensive. It explains purpose, parameters, return format, result contents, flexible dataset types, and next-step tool references. The presence of an output schema reduces the need to detail return values, but the description still covers the essential content. No critical gap remains.

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 provides zero description coverage (0%). The description fully compensates by documenting both parameters: analysis_type with a list of examples ('survival', 'safety', 'efficacy', etc.), and response_format with values, default, and semantics ('markdown' for human-readable, 'json' for machine-readable). This is more detailed than most schemas and gives the agent everything needed to choose valid values.

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 opens with a clear verb+resource: 'Search for Teal modules that perform a specific type of analysis.' It explicitly states the tool finds modules based on analysis type, and further differentiates from siblings by noting it helps 'when you know what analysis you need but don't know which module to use.' This clearly distinguishes it from list_modules and get_module_details.

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: 'when you know what analysis you need but don't know which module to use.' It also names alternatives for follow-up actions: 'Use tealflow_get_module_details to see typical datasets and tealflow_check_dataset_requirements to verify compatibility.' This gives the agent concrete guidance on when and how to use the tool 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?

Annotations indicate idempotentHint=true and destructiveHint=false, and the description aligns with these while adding significant detail: it discloses that locked versions are respected, only missing packages are installed when a lockfile exists, and initialization vs. restoration behavior. It also lists error types and the exact steps performed, providing transparency beyond the 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?

Though lengthy, the description is efficiently structured with headers (Behavior, Steps performed, Args, Returns, Error Types, Examples) and no redundant sentences. Every section adds value: behavior details, parameter warnings, error taxonomy, and example usage. It is appropriately sized for a tool with conditional logic and multiple failure modes.

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?

The description is self-contained: it explains the tool's purpose, step-by-step process, inputs with warnings, output format, error types, and examples. The output schema existence is supported by a clear account of what is returned. Given the tool's moderate complexity (lockfile handling, R dependency installation), this description fully equips an agent to select and 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?

The input schema has 0% description coverage, but the description fully compensates by explaining both parameters. It warns that project_path must be absolute, explains why relative paths resolve to the MCP server's directory, and specifies response_format values ('json' or 'markdown') with defaults. This adds crucial meaning that the schema lacks.

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 opens with a specific verb+resource statement: 'Prepare an R project directory so it is ready to run Teal Shiny applications.' It then clearly states it 'initializes an renv environment and installs required packages,' naming the exact packages. This distinguishes it from sibling tools like tealflow_snapshot_renv_environment, which handles snapshotting rather than setup.

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 gives clear context for when to use the tool: when preparing an R project to run Teal apps. The Behavior section explains how it handles existing vs. missing lockfiles, giving implicit guidance on when restoration vs. fresh initialization happens. However, it does not explicitly compare to alternatives (e.g., snapshot tool) nor state when not to use it, so it falls slightly short of a 5.

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?

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds useful context about writing to renv.lock, only snapshotting packages used in project code, and lists specific error types. It does not contradict annotations, though it could be slightly more explicit about overwriting an existing lockfile.

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 markdown sections for purpose, usage, requirements, arguments, returns, errors, and examples. It is somewhat long, but every section contributes value, especially the absolute path warning and error type list. A slightly shorter version could be more concise, but the structure and front-loading are 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?

The description covers when to use, prerequisites, parameter semantics, return value summary, error types, and a note about library() calls. Since an output schema exists, the lack of detailed return format documentation is acceptable. The context is complete for a well-understood tool with moderate 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?

The input schema has zero descriptions, but the description fully compensates by explaining that project_path must be an absolute path and warning about relative path resolution, and by defining response_format values ('json' or 'markdown'). This adds significant meaning 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 states 'Create an renv snapshot of the current R project environment.' with a specific verb ('Create'), resource ('renv snapshot'), and scope ('current R project environment'). It clearly distinguishes from the sibling tool tealflow_setup_renv_environment by noting that renv must be initialized first.

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?

An explicit 'When to use this tool' section lists concrete scenarios such as after installing or updating packages, before sharing, and for reproducibility. It also provides a requirement referencing tealflow_setup_renv_environment, which acts as a clear alternative/context for when this tool should not be used.

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