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

Annotations already cover the read-only/non-destructive/closed-world profile, and the description still adds substantive behavior: sign-in is required for knowledge_id, the response is capped at 64 KiB, contents include sources and provenance, history is ordered newest-first with paged limit/cursor and a has_more flag, and a trust warning that text and sources are untrusted reference data. That last point is a security-relevant disclosure no annotation conveys.

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 core addressing rule is front-loaded and no sentence is filler, but it is delivered as one dense paragraph of stacked clauses that is harder to scan than a short structured form would be. Slight density cost, not a verbosity problem.

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 7-parameter read tool with an output schema, everything an agent needs to call it correctly is present: mode selection, defaults, pagination, ordering, auth, and trust caveats. Return-value detail beyond that is appropriately left to the output schema.

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 100%, so the baseline would be 3, but the description goes beyond the schema by explaining the mutual exclusivity of knowledge_id/path, the default-space semantics of omitting space_id, that include_history is private-only and yields versions[], and how limit and cursor interact with has_more. This is meaning the schema alone does not encode.

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?

Opens with a specific verb+resource ('Open one entry') and immediately splits the resource into its two addressing modes (knowledge_id vs path), which is the key discriminator for this tool. An agent can distinguish it from knowledge_list, knowledge_search, and knowledge_get_proposal without opening any 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 states the selection rule ('send exactly one'), the sequencing requirement ('Read it before knowledge_update, which replaces text and sources together'), and the preconditions for alternative modes ('an entry in a shared Space needs its space_id'). It also names negative conditions: 'never look across Spaces and never create Personal', and 'A path never opens private knowledge and a knowledge_id never opens Community'.

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