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

readOnlyHint=true already establishes the safe-read profile, and the description adds that the result is curated current knowledge rather than raw files. It does not say what happens when the section name is not in the table of contents, nor anything about size or structure of the returned article.

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?

Two sentences, zero filler: the first defines the return value, the second tells the agent where to get the argument. The prerequisite is stated in the position where it matters most.

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?

An output schema exists, so return structure need not be described, and the annotations cover safety. What remains is small but real: the meaning of the map concept and of project_id are left implicit.

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 both parameters rely on the description. The section parameter is well served: its valid values come from the get_project_context/get_project_map table of contents, with examples given. project_id is not addressed at all, leaving half the parameters unexplained.

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 the returned resource concretely: an article for one shelf of the map with topical knowledge, illustrated by example categories ("Решения", "Грабли"). That distinguishes it from sibling readers like read_project_file and read_journal, though the notion of a "map shelf" is never defined for an agent unfamiliar with the concept.

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 tells the agent to call it with a section taken from the table of contents returned by get_project_context or get_project_map, which is a clear entry condition and points at prerequisite tools. It gives no exclusion criteria (e.g. when to prefer read_project_file over a map shelf) and cites get_project_map, which is not in the sibling list.

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