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

Annotations only declare readOnlyHint/openWorldHint, and the description adds substantial context beyond them: the 60,000-character truncation with a truncated flag, immutability of versions, changedSince semantics for edited sources, the verified signature check, that links are created in the app not via this tool, and the private-artefact visibility rule. It also warns to treat artefact text as reference material rather than instructions, a genuine safety disclosure.

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?

Front-loaded with the core purpose, then bulleted modes (id vs topicId) and a bulleted return-value breakdown, so an agent can scan it quickly. Every line carries information, though the return-value section is dense and could be marginally tighter.

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?

There is no output schema, and the description compensates by enumerating the returned fields for id reads (markdown, sources, links, verified) and the ordering for topicId reads (newest first). Combined with the mutual-exclusion rule and version defaulting, an agent has everything needed to call it correctly and interpret results.

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 coverage is already 100%, so the baseline is 3, but the description adds real meaning: the exactly-one-of relationship between id and topicId, that the two are mutually exclusive modes rather than optional extras, and what each mode returns. It does not restate the limit bounds (default 20, max 50) beyond what the schema gives, which 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?

States a specific verb and resource ("Read an artefact, or list the artefacts made from a topic") and immediately defines what an artefact is (documents, slide decks, PDFs, web pages) plus the versioning model. The dual id/topicId modes are spelled out so an agent can distinguish the two behaviours without opening the schema.

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 says "Pass exactly one of: id ... topicId ...", which is a clear when-to-use-each rule for the two modes, and notes version defaults to latest. It does not name sibling tools (e.g. engramic_topic for topic metadata) or state what to do if both or neither is supplied, so routing against siblings is left implicit.

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