get_issue_primer

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

The description explains that it performs automatic normalization of the issue string, which is a useful behavioral detail beyond the schema. Since no annotations are provided, this partial transparency is helpful but still lacks details on what the primer includes in terms of length or format. It is not contradictory, but it does not fully disclose the behavior.

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 compact, using emojis and symbols to structure the content, and front-loads the purpose. It is efficient, though the use of emojis might reduce formality, but the info density is high and every sentence serves a purpose. It is concise and structured well.

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 has only one parameter and no output schema, the description covers the essential aspects: what it does (primer content), how to use it (issue input), and a key behavior (normalization). It is sufficiently complete for the tool's complexity, though it could mention the return format or length, but that is minor for a primer tool.

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 schema only provides the parameter name and type, with 0% cover in the schema description. The description compensates by explaining that 'issue' can be a standard issue name or raw string, and that it will be automatically normalized. This adds meaningful semantics beyond the schema, making the parameter usage clear.

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 states a clear purpose: it prepares a study primer for a specific issue, including signal identification, prerequisite concepts, and exam points. It distinguishes itself from siblings like get_topic_primer and get_issue_chain by focusing on the primer aspect, though it does not explicitly name them. The verb and resource are specific (get primer for issue), and the action is clear.

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 says it is a 'must-read before doing questions' and indicates that the issue parameter can be a standard name or raw string, which implies when to use it. However, it does not explicitly state when not to use it or compare with alternative tools like get_topic_primer. The usage context is implied but not fully explicit.

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