sumo_qa_scan_repo

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description reconciles the surprising readOnly=false by disclosing the optional on-disk write via write_to. It also discloses determinism guarantees ('deterministic on the same repo state except for project.generated_at'). It does not address whether write_to overwrites an existing file, which is the main remaining behavioral gap.

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 core purpose and return shape, then usage phrasings, then parameter notes, so an agent gets the essentials first. It is somewhat long due to the five-item phrasing list, but each sentence earns its place and nothing is padded.

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 no output schema, the description takes on the obligation to describe returns and does so concretely (counts by kind/type/confidence), plus the optional artifact path and its determinism caveat. Remaining gaps are minor: no mention of error conditions, repo size limits, or confidentiality of the written artifact.

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 carries the full burden and largely meets it: root is described as absolute or relative to the server's working directory, generator_version defaults to the installed version, and write_to is optional and writes the full artifact to a JSON path. It adds real meaning the bare schema lacks, though it omits any format expectations for generator_version.

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 first sentence states a specific verb and resource ('Walk a repository and return a compact summary of its QA-relevant shape') and enumerates exactly what is returned: node counts, likely_tests edges by confidence, command counts by kind, warning counts by kind. That is far more specific than a name restatement, though it never names a sibling such as sumo_qa_query_repo_map to disambiguate scanning from querying.

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 'Common natural-language phrasings that map to this tool' block gives concrete invocation contexts ('map this repo', 'generate the repo-map artifact for X'), which is clear when-to-use guidance. It stops short of 5 because it names no exclusions or alternatives (e.g., when to query an existing map instead of rescanning).

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