synapse_causal_window

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

Annotations are not provided, so the description carries the responsibility. It describes the tool's query behavior (surfaces facts, returns ranked list) and implies it is read-only by stating it returns results and does not mention modifications. However, it does not explicitly state that the tool has no side effects or that it does not modify data. For a causal-window query tool, the lack of explicit side-effect disclosure leaves minor ambiguity.

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 description is well-organized: a one-sentence summary, a technical explanation of the matching criteria, an illustrative analogy, a note on correlation vs causation, and a clear Args list. The analogy adds helpful context but could be considered slightly verbose. Overall, it is concise and each sentence contributes to understanding the tool's function and usage.

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?

The description covers the tool's purpose, behavior, parameters, and the nature of results (ranked list). Since an output schema exists, the description does not need to detail return fields. It omits edge cases or error handling, but these are not typically required for basic tool invocation. The provided information is sufficient for an agent to decide when and how to use it.

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?

Despite the schema having no property descriptions, the tool description includes an Args section that explains all three parameters: effect_entity (the thing whose causes you're hunting), before (ISO date/datetime when effect was observed), and within_days (how far back to search, with default). This provides both meaning and usage context, fully covering the schema gaps.

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 clearly states the tool's purpose with a specific verb ('Find candidate causes') and identifies the resource (facts) and the mechanism (temporal correlation, valid_from window, entity sharing). It also distinguishes itself from other tools by explicitly framing the correlation-vs-causation role. This is more specific than a generic 'search' and leaves no ambiguity about what the tool accomplishes.

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 description provides a concrete usage scenario ('track everything you ate to find what caused the headaches') and clarifies that the tool returns correlation, not causation, which sets expectations for interpretation. However, it does not explicitly mention alternative tools (e.g., synapse_timeline or explore_connections) or state when not to use this tool. It gives enough guidance for typical use but lacks direct comparisons.

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