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

Annotations already declare readOnlyHint=true, but the description adds real value beyond them: it narrows the constraint to 'only GET is allowed' and states the return shape ('parsed JSON'). It does not mention auth requirements, error behavior on a bad path, or pagination semantics, which is the remaining gap.

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?

Four compact sentences, front-loaded with the escape-hatch framing and the read-only constraint, each carrying distinct information (scope, restriction, format rule, return type). No filler.

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 single-parameter passthrough tool with no output schema, the description covers the essentials: what it does, the read-only limit, how to format the path, and that it returns parsed JSON. It omits error/edge-case behavior for invalid paths, which keeps it short of fully complete.

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% and the schema already documents the path parameter, so baseline would be 3. The description adds genuinely useful meaning by clarifying that the caller must include the leading slash and the query string in the same argument, with concrete examples ('/article.json?_page=2').

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 (GET) and resource (any KnowledgeOwl API path not wrapped by a dedicated tool), and explicitly positions itself against the sibling tools that wrap common paths. An agent can immediately tell this is the generic fallback rather than a dedicated read tool.

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 phrase 'not wrapped by a dedicated tool' effectively tells the agent to prefer the sibling tools and reach for this only as a fallback, and 'READ-ONLY — only GET is allowed' rules out write usage. It stops short of naming a specific sibling or spelling out an explicit preference order, so it is clear but not fully prescriptive.

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