get_source_repo_map

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

With no annotations, the description carries the full burden and delivers rich behavioral details: status types (threshold_exceeded, building, waiting, success, error), resource management implications (token usage, timeout adjustments, file count thresholds), and scope intersection behavior. It also discloses response metadata (override_guidance, excluded files, completion status). No contradictions with annotations exist.

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 (PARAMETER, RESPONSE CHARACTERISTICS, Scope Control Options, Response Metadata) and front-loaded with a clear purpose statement. It is somewhat verbose and slightly redundant (e.g., resource management points overlap), but each section adds relevant operational information. It earns its length for a complex tool, though it could be tightened.

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 (6 parameters, no output schema, no annotations), the description provides extensive context: prerequisite, behavioral statuses, resource trade-offs, scope controls, and metadata. It is missing explicit coverage of the branch and cache_strategy parameters, and the response format beyond status types isn't described. Still, it gives enough for an agent to select and invoke the tool correctly in most scenarios.

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 description compensates for the 0% schema coverage by explaining repo_path with examples and normalization, files/directories with intersection logic, and max_tokens with token control nuances. However, it omits documentation for 'branch' and 'cache_strategy' parameters, leaving two of six parameters semantically unexplained. Overall, the semantic coverage is strong but incomplete.

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 'Retrieve[s] a semantic analysis map of the repository's source code structure, including file hierarchy, functions, classes, and their relationships.' This is a specific verb and resource, distinct from sibling tools like get_repo_structure or get_repo_documentation. The prerequisite mention ('must be previously cloned via clone_repo') further clarifies the context.

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

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

The description provides clear usage context by stating that the repository must be cloned first, and details scope control options (files, directories, intersection) with a note supporting 'broad and focused analysis strategies.' It does not explicitly name alternative tools or state when not to use this tool, but the context is sufficient. There is an implicit exclusion: if the repo isn't cloned, you should use clone_repo first.

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