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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds meaningful behavioral detail beyond that: it enumerates what is returned (metadata, decisionProfile dimensions, notes, typed relations) and explicitly states that source evidence and raw URLs are omitted. This helps set expectations without contradiction.

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 a single, dense sentence that front-loads the primary action and then lists the return contents plus the key omission. Every phrase earns its place, with no fluff or repetition of annotation fields.

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?

For a read-only tool with an output schema and 100% parameter coverage, the description is largely complete: it names the lookup mode, return fields, and a notable exclusion. A minor gap is that it does not explicitly state that at least one of id or slug should be provided, though this is strongly implied by 'by stable id or slug.'

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%, so the baseline is 3. The description adds value by clarifying that id and slug are alternative stable lookup keys and by framing them as 'stable,' which is not fully captured in the schema. It does not deeply elaborate on the language parameter, but the schema already explains that behavior well.

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 uses a specific verb ('Read'), names the exact resource ('public entity from Zhiyong AI's knowledge graph'), and states the lookup mechanism ('by stable id or slug'). It also distinguishes itself from siblings by focusing on reading one entity, while search_knowledge_graph finds entities and compare_knowledge_entities compares them.

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 clearly implies this tool is for fetching a single known entity when you have its id or slug. It does not explicitly contrast with search_knowledge_graph or compare_knowledge_entities, but the 'by stable id or slug' phrasing provides enough context for an agent to select it over alternatives when a specific identifier is already known.

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