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

With zero annotations the description carries the full burden, and it discharges it: it declares determinism, error contracts ("no_tests_found" with message+warnings; "invalid_argument"; "Malformed/oversized input never raises"), warning surfacing for dropped rows/unrecognised columns/duplicate run_ids, and the exact decision rules for flaky (pass_rate strictly between flaky_min and flaky_max with >=3 non-skipped executions) and ever-failing (zero passes over >=3 executions). The skipped-tests rule ('NOT failures') and the 1-2 run caveat prevent two classic misreadings of the output.

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?

Front-loaded with the highest-value facts (deterministic, exactly-one-of, array form for multi-run), but the body is a single ~350-word block with no paragraphing or bullets, and error behavior is restated twice (the no_tests_found paragraph and the closer about 'invalid_argument' | 'no_tests_found'). The length is defensible for a 5-param, 0%-coverage, no-output-schema tool, but the formatting makes scanning harder than it needs to be.

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?

No output schema exists, so the description enumerates the returned fields itself (runs, total_tests, executions, overall_pass_rate, flaky, ever_failing, never_run, slowest, failure_clusters, per_run, warnings, skipped_executions, skipped, mixed_outcome). Combined with the documented error shapes and threshold semantics, an agent has everything needed to call it and interpret the result on the first try.

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?

This is the strong point given 0% schema coverage: every one of the five parameters is explained — junit_xml's three accepted shapes including the stringified-'[' client quirk, csv_text's required/accepted column names and status synonyms plus duration unit heuristics, reference_tests' "classname::name" identity format and ambiguous-bare-name handling, and the 0 <= flaky_min < flaky_max <= 1 constraint. It falls short of a 5 only because defaults (0.2/0.8) are left to the schema and column-name semantics are dense enough to require careful reading.

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?

States a specific verb and resource — deterministic health metrics (flaky / ever-failing / never-run / slowest / failure clustering) computed from real test execution data — and explicitly distinguishes itself from LLM-based paths ("no LLM anywhere in this call path; write your own narrative"). No sibling tool (list_kb_sources, estimate_qa_effort, etc.) overlaps with this, so an agent can route on the first clause alone.

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?

Gives an explicit mutual-exclusion rule ("Provide exactly one of junit_xml or csv_text") and then names the alternative mode for the other use case: single run as a plain XML string vs. multiple runs as a JSON array of {run_id, xml} objects or bare XML strings. It also states the fallback behavior when neither form parses, and tells the agent to author its own narrative rather than expecting prose back.

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 carries the full burden and does so thoroughly: it discloses determinism/no-LLM, the indicative_tmmi_level cap at 3 with the TMMi no-skip rationale, the branch behavior for AI/ML mentions including negated ones, keyword-detection limits, and non-English handling. The three distinct status outcomes (ok, insufficient_content, not_a_qa_description) are spelled out precisely.

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 core purpose is front-loaded and every sentence carries substantive information about a non-obvious edge case, so the length is defensible. The structure is a single dense paragraph with heavy parenthetical nesting, which makes the branch conditions harder to scan than they need to be.

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?

Despite having no output schema, the description enumerates the full return shape (status, indicative_tmmi_level, both dimension score dicts, notes, findings, disclaimer, caveats, stats, kb_version) and explains the semantics of the conditional fields. An agent has everything needed to call it and interpret the result without guessing.

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 0% and the single parameter has no schema description, so the description must compensate — and it does: it defines what project_description should contain, the ~200-character minimum after stripping AI-disclosure boilerplate, the vocabulary requirement that separates a valid input from a recipe or meeting notes, and the language constraint that flips score_reliable.

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 leads with a specific verb+resource: deterministically assess QA process maturity from a free-text project/process description, naming the exact scope (10 TMMi process areas, Level 2 Managed + Level 3 Defined). It explicitly distinguishes itself from the sibling tools by framing the output as findings the caller must narrate themselves, versus review/estimate 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?

It clearly states the valid input context (a free-text project/process description or a pasted Test Strategy/Risk Register) and the conditions under which it does not apply (under ~200 characters, no QA vocabulary). It does not, however, explicitly compare itself to siblings like review_qa_document or estimate_qa_effort, leaving the agent to infer which to choose.

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 carries the full burden and does so: it specifies the validation error shape ({"error": "validation", "fields": {...}}), guarantees no crash, rejects negative team sizes and non-positive timelines, rounds decimal headcounts half up with a warning, and defines the sign of capacity_gap and when methodology_note is a label only. That is genuine behavioral disclosure beyond anything structured.

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?

Front-loaded well with the deterministic-method summary, but the body is a dense run-on block (a missing period causes 'in that same shape Success returns...' to merge two ideas) and the capacity sign convention is explained twice. The content earns its place; the presentation does not.

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 twelve-parameter tool with no output schema and no annotations, the description compensates by enumerating the return fields (baseline, multipliers, pert_activities, capacity, confidence_score, data_quality_score) and the error contract. What remains missing is input-side completeness: acceptable value formats for the many string fields and the eleven-vs-twelve field discrepancy.

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 0% across twelve bare string fields, and the description only adds semantics for three of them (team_qa_size/team_dev_size, timeline) plus the field-mirrors-intake framing for the rest. Fields like project_type, methodology, existing_automation and compliance_requirements get no hint of accepted values or formats, and the 'all eleven fields' count contradicts the twelve properties 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?

Opens with a specific verb+resource and method: 'Deterministic QA effort estimate (PERT + complexity multipliers + team capacity + confidence score)'. It also disambiguates itself from narrative-generating behavior ('no LLM narrative; write your own from these numbers'), making its role clear, though no sibling tool is named explicitly.

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 signals how to consume the output ('write your own from these numbers') and states that all fields are needed, but never says when to choose this over assess_qa_maturity or analyze_test_results, nor what situations make an estimate inappropriate. Usage is implied rather than stated.

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

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

No annotations are present, so the description carries the full burden. It accurately describes the return structure (categories mapping, kb_version, doc_count), indicating no side effects or destructive actions. It is transparent about listing all documents, but does not mention limitations like pagination or rate limits, which would be expected for a full list.

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 directly states the action and includes an example of the return format. Every word is meaningful and necessary. It is front-loaded with the core function and immediately useful to an agent.

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 zero parameters and no output schema, the description provides sufficient information: the core action and the return structure. However, it does not clarify the scope of 'knowledge base' (e.g., global or per-user) or mention potential performance implications for large datasets. It is adequate but could be more 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?

The input schema has zero parameters, and schema coverage is 100%. The description adds value by detailing the output structure, which is not in the schema (no output schema provided). Since there are no parameters, the description effectively compensates for the lack of output 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 'List every document in the knowledge base, grouped by category.' This is a specific verb ('list') and resource ('documents in the knowledge base'), and it distinguishes from sibling tools like 'retrieve_qa_knowledge' which focus on QA, 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?

No explicit guidance on when to use this tool versus alternatives is provided. While the description is clear, there is no statement about when not to use it or which sibling to prefer in various contexts. The use case is implicitly straightforward but not guided.

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 carries the full burden and does so: cold-start latency (~30s on first call after server start), a documented return shape including match-tier logic (strong >=0.55 plus content-term overlap, moderate >=0.40, weak), near-duplicate collapse, clamping of k and out-of-range min_score reported in warnings, and structured {error: invalid_argument} instead of raising. These are exactly the operational traits an agent cannot infer from the schema.

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 most important facts (what corpus, what is missing, cold start) are front-loaded before the return-shape detail, and nearly every clause conveys usable information. It is dense and parenthetical, however, and the return-shape/error discussion runs together rather than being segmented, which costs some scannability.

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?

There is no output schema and no annotations, so the description must explain return values and failure modes — it documents the chunk fields, best_score, low_relevance, note and warnings, plus the empty-result path. For a 4-parameter retrieval tool with no structured metadata, nothing an agent needs in order to call and interpret it 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 coverage is 0%, so the description must compensate and it does: k is clamped to [1,20], min_score is cosine similarity with default 0.40 where 0 disables filtering, category must be one of five enumerated values, and an empty query or bad category returns a structured error. This adds real semantics beyond the bare titles 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?

States a specific verb+resource ('Retrieve grounding chunks from the local QA knowledge base') and immediately scopes the corpus by enumerating included guide types and explicitly excluded sources (ISTQB/OWASP PDFs). This tells an agent both what the tool returns and where its coverage boundary lies, which sets it apart from list_kb_sources.

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?

Gives clear conditional guidance: when no chunk clears min_score, 'answer from your own knowledge and tell the user the KB had no match', and when the best hit is not strong, use only chunks that really answer the question. It also warns that fundamentals like boundary value analysis are often absent, steering the agent away from futile queries. It does not explicitly contrast itself with list_kb_sources or the analysis siblings, which keeps it from 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?

With zero annotations the description carries the full burden and delivers: no LLM in the call path (determinism), structured errors instead of exceptions for invalid doc_type, short-document handling with overall_score=0, explicit QA-signal exception, non-QA and oversize statuses, non-English scoring with score_reliable=false, and no fabricated citations. Nearly every failure mode an agent could hit is disclosed.

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?

Core purpose and rubric are front-loaded before the edge-case detail, and nearly every sentence carries decision-relevant information. It is, however, a single dense block of considerable length with some hedging qualifiers that could be tightened into a short bulleted edge-case 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?

No output schema exists, yet the description enumerates the return contract ({doc_type, overall_score, dimension_scores, findings, stats, status, language, language_warning, score_reliable, detection_confidence, detection_note, hint, kb_version}). Combined with status semantics and citation-resolution behavior, nothing an agent needs to call this correctly 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 coverage is 0%, so the description must compensate and does: all four doc_type values are enumerated with behavior ('auto' runs a keyword classifier and reports its assumption; invalid values return a structured error). document_text constraints are also implied through the ~200-character threshold and front-matter/footer stripping rule.

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?

States a specific verb and resource — deterministically review an existing QA document (Test Plan, Test Strategy, or test case list) — and names the exact rubric dimensions used. This is unmistakably distinct from siblings like estimate_qa_effort or analyze_test_results, which operate on different inputs and outputs.

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?

Clear context for use: reviewing an existing document, with the contract that the caller writes its own narrative from the returned findings. Doc_type selection guidance is explicit, including when 'auto' is appropriate. It stops short of naming sibling alternatives or stating when not to use this tool (e.g., versus retrieve_qa_knowledge for source lookup).

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