knowledge_document_context

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds almost no behavioral context: it does not explain what the tool outputs, how it processes inputs, or what side effects (if any) are expected. It neither contradicts annotations nor enriches them.

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 short, but under-specification is not the same as conciseness. A single vague phrase without a clear subject-verb-object structure does not front-load the purpose. It reads more like a topic tag than a functional description.

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?

This is a high-complexity tool with 21 parameters and close sibling tools, yet the description is practically empty. Nothing tells an agent about the tool's scope, how to choose between plan and section, what evidence types are relevant, or how this differs from knowledge_document or knowledge_context. The output schema and annotations mitigate some gaps, but they cannot replace basic operational orientation.

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 only 5% across 21 parameters, so the description must compensate. It barely does: 'plans' and 'section evidence' loosely map to the two action enum values (plan and section), but essentially no other parameters (query, audience, max_pages, page_paths, required_evidence, etc.) are clarified. This leaves an agent guessing at most of the input semantics.

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 'Document plans and section evidence.' is a fragmented, ambiguous phrase. It fails to state a clear verb and resources: 'Document' could be a noun or a verb, and 'plans and section evidence' are vague objects. It does not convey whether the tool creates a plan, gathers evidence, or both, and it does nothing to distinguish it from sibling tools like knowledge_context or knowledge_document.

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?

There is no usage guidance whatsoever. The description does not mention when to prefer this tool over knowledge_document, knowledge_context, or other siblings, nor does it state any prerequisites or when not to use it. The only implicit hint is the schema's action enum, which is separate from the description.

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