agora_detect_contradictions

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

With no annotations at all, the description carries the full behavioral burden, and it does little beyond implying a filtered read ('active'). It does not state that the operation is read-only, whether it requires any permission or access level, or how many relations are returned, all of which matter for a graph-traversal tool.

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?

A single front-loaded sentence with no filler, which is efficient. It leans toward under-specification rather than verbosity, but there is no structural waste to penalize.

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 return values need not be described. However, for a zero-annotation tool with 0% parameter coverage, the description is too thin: it omits read-only guarantees, the meaning of 'active', and any orientation against similar read/graph siblings.

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% for the single claim_id parameter, so the schema itself offers no meaning. The description only repeats that a Claim is involved, adding no format, identifier-syntax, or existence requirements to compensate for the coverage gap.

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 and resource (find contradiction relations around a claim), which an agent can distinguish from relation-creating siblings like agora_relate_claims. However, it does not distinguish itself from adjacent read tools such as agora_get_claim or agora_get_argument_neighborhood, leaving some ambiguity about what unique output it produces.

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?

No guidance on when to use this versus alternatives like agora_get_argument_neighborhood or agora_get_claim, and no exclusions or prerequisites. The word 'active' hints at a filtering condition but never explains what makes a relation active or when this lookup is appropriate.

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