query_blender_knowledge

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

With no annotations present, the description must carry the behavioral burden, and it does establish that this is a read-only lookup against a 'verified' source that returns JSON entries, guidelines, and code snippets. It omits other behavior an agent would want: whether results are ranked or truncated, how many entries come back, and whether an empty result indicates an unknown topic.

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 purpose sentence is front-loaded and the Args/Returns block is structured and easy to scan, with no filler text. It is slightly verbose for a two-parameter search tool, but every line carries information.

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?

An output schema exists, so the description does not owe a full return-value spec, yet it still summarizes the payload (knowledge entries, guidelines, code snippets). Both parameters are documented despite zero schema coverage, and the remaining unknowns (topic value set, result limits) are modest for a read-only search tool.

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 0%, so the description must compensate, and it does: 'query' is explained as search keywords with four concrete examples, and 'topic' is marked optional with four example path-like values ('00-foundations', '10-modeling', etc.). The gap is that topic is illustrated rather than enumerated, so the agent cannot be sure those are the only valid values or what happens with an unknown topic.

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 names a specific verb and resource ('query the verified bpy 5.2 knowledge base') and scopes it to modeling, shading, modifiers and gate rules, which clearly separates it from the sibling tools (validate_part_spec, execute_blender_pass, blender_runtime_status) that act rather than look things up. It stops short of explicitly contrasting itself with those siblings, so it gains the point only by implication.

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 example queries ('bevel modifier', 'pbr shader', 'watertight mesh') imply the kind of situation this tool is for, and the 'verified' framing implies it should be preferred over guessing API details. However, there is no explicit when-to-use, when-not-to-use, or statement of how this relates to execute_blender_pass or validate_part_spec, leaving the routing decision to inference.

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