Read Guide

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's burden is lower. It adds the useful framing that the target is human-oriented documentation and lists the topic domains, but it says nothing about how content is returned, whether a topic name must match exactly, or what happens for an unknown topic. An output schema exists, so return format need not be described, which keeps this at an adequate rather than deficient level.

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 front-loaded sentence with the verb and resource first, followed by the scope enumeration. The trailing list of five content areas is slightly padded but still informative and not redundant; nothing is wasted in preamble.

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 is simple: one optional parameter, full schema coverage, an output schema that handles return values, and a readOnly annotation covering safety. The description supplies what those structured fields cannot — that this is human-facing guide material and what it contains — leaving only minor gaps around topic matching.

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% and the single 'topic' parameter already documents that an empty value lists available articles. The description enumerates content areas but does not map them to valid topic values or explain matching behavior, so it adds no meaning beyond the schema. Baseline 3 is appropriate.

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 names a specific verb ('Đọc' / read) and resource ('tài liệu hướng dẫn shipfast cho người' / the human-facing shipfast guide), and it enumerates the content areas the guide covers (getting started, organization, meaning, development, upgrade). That is far clearer than a tautology, but it makes no attempt to distinguish itself from siblings such as check, status, or scaffold_project, so an agent must infer that this is documentation-only rather than operational.

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?

Usage is only implied: the enumerated sections suggest the tool is for onboarding/reference reading, but the description never states when to choose this over check or status, nor any exclusions. The 'leave blank to list' behavior lives in the schema rather than the description, so guidance is present but not articulated in the definition itself.

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