quipu_rule_query

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

Annotations already establish readOnly=true and non-destructive, but this description adds genuinely non-inferable behavior: failed or incomplete reads must be treated as UNKNOWN rather than absence, results are scoped to the current ROOT, and there is no implicit boolean coercion of results. That is exactly the kind of failure-mode and result-interpretation context annotations cannot carry.

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?

Three tight sentences, front-loaded with the operation and result vocabulary, then the read-scope caveat, then the authority caveat; nothing is redundant. The compaction borders on terseness, but no sentence fails to earn its place.

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 tool with five required, wholly undocumented parameters and no output schema, the description supplies the result enum and the UNKNOWN-on-failure rule but leaves the agent unable to construct a valid call (what goes in positive_predicate vs negative_predicate, what judgment_policy accepts, what an object IRI vs string means). It answers result interpretation better than invocation.

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% and six parameters (subject, positive_predicate, negative_predicate, object, judgment_policy, witness_limit) carry bare type names only. The description obliquely gestures at 'judgment disposition' and positive/negative support but never explains any parameter's meaning, accepted values, or the role of witness_limit, so the compensation for the coverage gap is minimal.

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 read operation ('read explicit positive/negative support') and pins down the result vocabulary (supported/refuted/both/neither plus a judgment disposition), which tells an agent roughly what comes back. However, the phrasing is dense domain jargon and it never contrasts this with the many sibling query/lookup tools (quipu_query, quipu_verifier_authorized, quipu_search_facts), so disambiguation is left to inference.

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?

'Current ROOT only' is a scope constraint, not usage guidance, and 'No action authority' is a negative capability statement rather than a when-to-use rule. There is no statement of which sibling tool to pick when an agent wants general queries, verification, or search instead of explicit support evaluation.

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