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

With no annotations provided, the description carries the full burden. It explicitly enumerates the output contents (decomposition, acceptance criteria, scenarios per layer, risk map, quality questions, test data, checklist), making it clear this is a read/analysis operation with no side effects. However, it doesn't specify output format or any constraints, but it is sufficient for a non-mutating 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 a single sentence that front-loads the main purpose and then lists the output components. It is efficient with no wasted words, though it is dense and could be slightly restructured for readability. Overall, it earns its length.

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 no output schema, the description adequately summarizes the tool's rich output (a framework with multiple sections). It covers the tool's behavior and what to expect, though it could mention the output format or any limitations. Still, it is complete enough for a comprehensive analysis 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?

The input schema already provides descriptions for all four parameters (story, context, tech_stack, feature_type) with 100% coverage. The tool description does not add additional parameter semantics beyond what the schema states, so it meets the baseline for full coverage without extra value.

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 it analyzes a User Story and returns a comprehensive QA analysis framework, listing specific components (decomposition, acceptance criteria, scenarios per layer, risk map, quality questions, test data, checklist). This distinguishes it from sibling tools that focus on specific test artifacts (e.g., create_gherkin_scenarios, generate_performance_plan).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for obtaining a complete QA analysis of a user story, but it does not explicitly state when to use this tool versus alternatives like generate_test_strategy or create_gherkin_scenarios. No exclusions or alternative guidance is provided, so usage context is only implicit.

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 output includes various scenario types and a step definitions checklist, which is helpful. However, it does not mention behavioral traits like whether the tool is read-only, any prerequisites for input quality, or output format constraints, leaving some uncertainty.

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 a single sentence that immediately states the core function, followed by a comma-separated list of inclusions. It is front-loaded, concise, and contains no extraneous words. Every part adds value.

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

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

Given the absence of an output schema and annotations, the description provides a fairly complete picture: it specifies input (acceptance criteria) and output content (scenario types, outlines, checklist). Minor details like output format (plain text vs. JSON) or error handling are missing, but the description covers essential usage information for a generative 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 coverage is 100% with basic but adequate descriptions for each parameter. The tool description adds no additional meaning beyond what the schema already provides (e.g., it does not explain how 'context' influences generation). Baseline 3 is appropriate as the schema covers the parameters, and the description does not enhance their 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 clearly states the tool creates BDD scenarios in Gherkin from acceptance criteria, listing specific output types (happy path, negatives, edge cases, Scenario Outline with tables, step definitions checklist). This verb-resource combination is distinct from sibling tools like analyze_user_story or generate_test_strategy.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when you have acceptance criteria and need BDD scenarios. However, it does not provide explicit guidance on when not to use this tool or suggest alternatives (e.g., when to use design_contract_tests instead). The context is clear but lacks exclusionary or comparative advice.

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 must carry the full burden. It indicates the tool returns a design output (non-destructive implied) but does not disclose potential side effects (e.g., interactions with Pact Broker), required permissions, or limitations. The optional pact_broker_url parameter hints at external calls, but this is not explained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences) and front-loaded with the core purpose. The output list is provided in the second sentence. However, the Portuguese language may reduce readability for English-only agents, and the structure could be improved with bullet points for quick 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 complexity of contract testing, the description provides a high-level overview of outputs but lacks details on how the tool processes inputs, assumptions about the environment, or what the returned structure looks like. No output schema exists, so the description should be more explicit about the format and usage of the output.

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 concise parameter descriptions. However, the tool description adds no additional meaning beyond the schema. It does not explain relationships between parameters, expected formats, or how to structure the 'interactions' input effectively.

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: designing Consumer-Driven (Pact) contract tests between consumer and provider. It uses a specific verb ('Projeta') and lists concrete outputs (interaction structure, provider states, matchers, versioning, CI/CD integration), making it distinct from siblings like design_integration_tests.

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?

No explicit guidance on when to use this tool versus alternatives. Sibling tools exist (e.g., design_integration_tests) but the description does not differentiate them or provide context for appropriate use cases, exclusions, or prerequisites.

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 exist, so the description carries full responsibility. It discloses what the tool produces (test structure, Testcontainers, scenarios) but omits behavioral traits like side effects (e.g., file creation), authorization needs, or persistence of results. The description adds some value beyond the schema but is not thorough.

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 a single, well-structured Portuguese sentence that front-loads the core action and then lists output elements. It is concise and clear, though it could be slightly more organized with bullet points for the return components.

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 complexity (5 parameters, no output schema, no annotations), the description is adequate but incomplete. It fails to specify the output format (e.g., text, code block), prerequisites, or how it interacts with sibling tools like 'analyze_user_story' or 'review_test_code'.

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%, providing baseline 3. The description does not add meaning beyond the schema; parameter descriptions are minimal ('Primeiro componente.'). It does not explain how parameters like integration_type influence the generated output.

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 designs integration tests between two components and specifies the output elements (Testcontainers, setup/teardown, scenarios). This differentiates it from sibling tools like 'design_contract_tests' by focusing on integration rather than contract testing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when two components need integration testing but offers no explicit guidance on when to use this tool versus alternatives (e.g., contract tests, performance plans). No conditions, exclusions, or prerequisites are mentioned.

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 bears full responsibility for behavioral disclosure. It mentions generating configuration with specific features (test stages, parallelism, caching, coverage, reports, quality gates), which gives some insight. However, it does not clarify the output format, whether it writes files, requires project files as input, or the extent of customization, making behavioral transparency moderate.

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 a single sentence that efficiently enumerates the tool's core capabilities. It is front-loaded with the main action (generating CI/CD configuration) and lists key features. Every part adds value, though it could be slightly more structured for quick 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 there is no output schema and the tool has 5 parameters (2 required), the description provides a good overview of what the generated configuration includes but lacks specifics on the output's nature (file type, location, template style). The thorough schema documentation partly compensates, but the description should clarify the deliverable format for complete contextual understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is 100% (all 5 parameters have descriptions), so the baseline is 3. The description adds minimal extra parameter context beyond listing the included features. It mentions 'tech_stack' and 'test_types' implicitly but does not elaborate on parameter usage, relationships, or defaults that aren't already 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 tool name 'generate_ci_pipeline' combined with the description clearly states it generates CI/CD configuration, specifically for GitHub Actions and others. The description lists included features like test stages, parallelism, caching, coverage, reports, and quality gates, making the purpose specific and distinct from sibling tools like 'generate_test_strategy' or 'quality_checklist'.

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 lacks any when-to-use guidance, prerequisites, or comparison with sibling tools. It does not explain when to use this tool versus alternatives like 'generate_test_strategy' or 'review_test_code', leaving the agent without context to decide correctly.

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 must carry the burden. It discloses that the tool generates a plan with scripts and guides, implying a non-destructive, output-producing action. However, it does not mention whether it modifies anything, requires authentication, or has side effects (e.g., file creation on disk). This is adequate but not rich.

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?

A single sentence efficiently conveys the full scope of what the tool generates, including test types, thresholds, commands, and analysis guide. No redundancy. However, for an agent that may not read Portuguese, the language choice could be a barrier, but that does not affect conciseness scoring.

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?

With 5 parameters, no output schema, and no annotations, the description is insufficient. It fails to specify what the tool returns (e.g., a file path, a string, a structured object) and how the agent should use the result. The guide mentioned is part of the generated content, but the return format is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning to any of the 5 parameters beyond what the schema already provides. It is a general overview rather than per-parameter enrichment.

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?

Description clearly states it generates a k6 performance plan including specific test types (smoke, load, stress, spike, soak), SLA-derived thresholds, execution commands, and analysis guide. The verb 'gera' and resource 'plano de performance' are specific and distinct from sibling tools like 'generate_test_strategy' or 'security_test_checklist'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool should be used when a k6 performance script is needed, but does not explicitly state when to use it versus alternatives (e.g., 'generate_test_strategy' for high-level planning). No exclusions or prerequisites are mentioned.

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 must communicate behavioral traits such as side effects, output format, or required permissions. The description only lists content components (e.g., pyramid, CI/CD flow) but does not clarify whether the tool saves output, returns text, or requires authentication. For a generative tool, the behavioral model is left entirely implicit.

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 a single sentence that front-loads the main action and enumerates the key output components. While efficient, it is a long compound sentence that could benefit from structural improvements (e.g., bullet points or clearer separation of ideas). No wasted words, but room for better readability.

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 complexity of generating a multi-component test strategy, the description provides a list of high-level constituents but lacks details on output format, level of detail, or what the agent can expect. With no output schema, the description should clarify the output's nature (text, structured plan, etc.). It is adequate for a brief overview but not fully complete for an agent to invoke confidently.

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 all five parameters having clear descriptions. The tool's description does not add additional meaning beyond what the schema provides—it lists the output components but does not map them to parameters or explain how inputs affect the generated strategy. The baseline of 3 is appropriate since the schema carries the 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 clearly states that the tool generates a complete test strategy and lists six specific components (adapted pyramid, tools per layer, CI/CD flow, coverage goals, execution SLA, phased roadmap). This distinguishes it from sibling tools that focus on narrower aspects like contract tests or performance plans. The verb 'Gera' (generates) combined with the resource 'estratégia completa de testes' provides a precise, actionable purpose.

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 does not explicitly state when to use this tool versus alternatives. While it implies that it is for generating a comprehensive strategy, there is no guidance on when a user should choose this over more specific tools like 'design_contract_tests' or 'generate_performance_plan'. The context of sibling tools suggests a need for differentiation, but the description does not address it.

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, the description must fully disclose behavioral traits. It only states it returns a checklist, but does not explain whether the optional artifact_content is used for analysis or ignored, whether the checklist is generic or content-specific, or any side effects. Safety and permissions are entirely undisclosed.

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?

A single sentence that front-loads the primary action (returns checklist) and lists supported artifact types. Every word is essential; no filler or 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 no output schema and no annotations, the description should cover return format, whether artifact_content is necessary, and typical usage context. It does not. For a 2-parameter tool with an enum, the description is too minimal to enable confident invocation by an AI agent.

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 coverage is 100% (both parameters have descriptions). The description adds natural language expansion of the artifact_type enum values, but does not add any new meaning beyond what the schema already provides. Baseline is 3, and the description barely meets it.

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 returns a quality checklist for a specific artifact type and lists eight concrete types (user story, test plan, etc.). This provides a specific verb+resource combination and helps distinguish from some siblings, though it does not explicitly differentiate from 'security_test_checklist'.

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?

No guidance is given on when to use this tool versus alternatives like 'analyze_user_story' or 'security_test_checklist'. There is no mention of prerequisites, when not to use it, or how to choose artifact types. The agent must infer usage from the tool name and sibling list.

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 bears the full burden. It mentions the output is a 'framework de análise' (analysis framework) with specific categories, which is helpful. But it doesn't disclose if the tool modifies any state, requires authentication, has rate limits, or what happens on failure (e.g., empty code input). For a read-only review tool without annotations, this is adequate but not fully transparent.

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 a single, front-loaded sentence that efficiently conveys purpose and output. Every part (verb, resource, review categories) earns its place. No fluff, but it could be slightly restructured for readability (the list of categories is dense) – hence not a 5.

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 review tool with no output schema, the description adequately explains the return value by listing analysis categories. The 4 parameters are well-documented in the schema, so no gaps there. However, for a tool that likely has complex behavior (e.g., language-specific heuristics), more detail on how language/framework affects the analysis would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema coverage is 100% with descriptions for all four parameters, so the baseline is 3. The description adds meaning by explaining that the tool returns a structured analysis, which hints at how the 'context' and 'language' parameters guide the review. However, it doesn't elaborate on format or defaults, so it's a minor lift above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description starts with a specific verb ('Revisa' – reviews) and resource ('código de teste' – test code), immediately stating what the tool does. It further clarifies the output by listing detailed analysis categories (design, anti-patterns, isolation, etc.), which clearly distinguishes it from siblings like 'generate_test_strategy' or 'troubleshoot_flaky_test'.

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 clearly implies this tool is for reviewing test code, which differentiates it from siblings that create (generate_test_strategy, create_gherkin_scenarios) or troubleshoot (troubleshoot_flaky_test) other aspects. However, it does not explicitly state when NOT to use it (e.g., for production code) or provide prerequisites.

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 of behavioral disclosure. It clearly states what the tool returns (a security checklist with specific components) and implies it is a read-only, consultative operation. It does not mention any side effects, required permissions, or rate limits, but for a checklist generation tool, the behavioral profile is sufficiently transparent.

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 a single, information-dense sentence that effectively conveys the purpose and scope without superfluous words. Every element (OWASP Top 10, adaptation to feature type, specific components) 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?

Given the moderate complexity (3 parameters, no nested objects, no output schema), the description provides a complete overview of the tool's function and output components. It could be enhanced by mentioning if the checklist is returned as text, structured data, or a JSON object, but this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the overall output context (security checklist) but does not elaborate on individual parameters beyond what the schema provides. However, the required parameter 'feature_type' is well-explained via its enum in the schema, and the description's context about OWASP enhances understanding of how the parameters are used.

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 returns an OWASP Top 10 security checklist adapted to the type of feature, including attack vectors, test cases, mandatory headers, SAST/DAST tools, and security acceptance criteria. This specific verb+resource combination distinguishes it from siblings like 'quality_checklist' (general quality) and 'analyze_user_story' (analysis, not checklist 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 implies usage for security testing of features by mentioning OWASP Top 10, attack vectors, and security acceptance criteria. However, it does not explicitly state when not to use it (e.g., for non-security testing) or provide alternatives like 'quality_checklist' or 'analyze_user_story' for different contexts.

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 must convey behavioral traits. It indicates the tool outputs hypotheses ordered by probability and includes code examples, but it does not disclose potential side effects (e.g., if it writes to any state), rate limits, or whether it requires authentication. The description is adequate but not exhaustive for a diagnostic 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 a single sentence that front-loads the primary action ('Diagnostica') and lists key outputs concisely. Every clause adds distinct information—hypotheses, steps, fixes with code, prevention policy—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?

The tool has 4 parameters (2 required), no output schema, and no annotations. The description clarifies the output types but omits the return format, pagination behavior, or error scenarios. Given moderate complexity, the description is functional but lacks details about practical usage (e.g., what happens if code is omitted).

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%, but each parameter's schema description is minimal (e.g., 'Código do teste (altamente recomendado para diagnóstico preciso)'). The tool description clarifies how parameters are used collectively (e.g., symptoms used to order hypotheses), adding value beyond the schema. It does not, however, explain the interplay between parameters or optional versus required fields in detail.

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 uses specific verbs ('Diagnostica', 'Retorna') and clearly identifies the resource ('testes instáveis (flaky)'). It lists multiple output types (hipóteses, passos de diagnóstico, correções, política de prevenção), which fully distinguishes it from sibling tools like analyze_user_story or generate_test_strategy that focus on different test lifecycle stages.

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 does not state when to use this tool versus alternatives like review_test_code or quality_checklist. It provides no explicit guidance on prerequisites (e.g., having test logs), contexts where it is inappropriate, or how symptoms should be structured for best results.

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