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

No annotations exist, so the description carries the full burden and delivers meaningful behavioral facts: parameter values are validated and escaped rather than spliced raw (a security/injection guarantee), and it requires the same role as brainkb_sparql (an auth prerequisite). It stops short of stating read-only nature or return/error behavior.

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?

Two tight sentences, front-loaded with the core action, and each clause earns its place by adding either workflow, safety, or auth information. No filler or restatement of the name.

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 2-parameter tool with no output schema and no annotations, it covers purpose, id provenance, param safety, and auth requirements adequately. It omits any hint of return shape or failure modes, a minor gap given the absence of an 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 description coverage is 0%, so the description must compensate. It clarifies that query_id refers to an id from brainkb_qa_list and that params is a name-to-value mapping that gets validated/escaped, which adds real meaning. However, it does not explain what parameter names or value types a canned question accepts.

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+resource ('Run a canned question from brainkb_qa_list by id') and distinguishes itself from the sibling brainkb_qa_list (which supplies the id) and from brainkb_sparql (raw query path). An agent can tell what it does 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?

Provides clear workflow context: the question comes from brainkb_qa_list, so that is the prerequisite step, and it notes the execution path parallels brainkb_sparql. It does not explicitly state when to prefer this over brainkb_sparql, so there are no stated exclusions.

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