investigate

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

'There are no annotations, so the description carries the full burden of behavior explanation. It does disclose the mode-based behavior and parameter applicability, which is useful. However, it does not describe the effects of running an investigation, whether it creates or modifies state, what the output looks like beyond the output schema, or any side effects or failure conditions.'

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 compact and front-loaded with the single-sentence purpose, followed by a tight Args block that covers all four parameters without redundancy. Every sentence contributes operational 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?

For a four-parameter tool with no annotations and 0% schema coverage, the description is largely complete: it provides action values, investigation name options, and parameter-specific rules. The main remaining gap is the expected inner structure of the 'params' JSON string for 'run', which is left to the caller to know. The existence of an output schema reduces the need to document return values, so the overall definition is still quite complete.

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 parameter burden falls entirely on the description, and it delivers. It explains each parameter in plain language: the accepted values of action, the role of name across modes, that params is a JSON string used only for 'run', and that element_id is a 'table:sys_id' identifier for 'explain'. It even lists available investigation names, making parameter choice actionable.

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 opens with a specific verb and resource: 'Run an investigation or explain a finding,' and then defines three distinct actions: 'run', 'explain', and 'describe'. It clearly maps the tool's scope, though it does not explicitly differentiate itself from siblings like 'describe', 'analysis', or 'audit', which leaves a small ambiguity.

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 gives clear action-specific usage context: name is 'required for 'run'', optional as a direct selector for 'explain', and a filter for 'describe'; params is 'run only'; and element_id is 'explain only'. This is strong contextual guidance, but it does not explicitly state when to prefer this tool over alternatives or when not to use it.

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