ps_corpus_stats

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the shape of the output (counts broken down by source, clusters, runs, claims, sessions), which is real value, but it never states that the call is read-only/side-effect free or whether it needs configuration to be valid.

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 short sentences, zero waste, with the returned-content inventory front-loaded and the usage cue at the end. Every clause earns 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?

An output schema exists, so return values need not be re-explained, and the description covers the semantic content of the overview well. However, with two completely undocumented optional path parameters, the definition is not quite complete for an agent deciding how to invoke 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?

Both parameters (config_path, periscope_path) have 0% schema description coverage, so the description must compensate and it does not — neither parameter is mentioned. An agent has no guidance on what these paths mean or when to supply them.

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 resource and the content it returns (stored items by source, clusters, runs, plus claim and research-session counters), which clearly distinguishes it as an aggregate-overview tool rather than a retrieval tool. It never names a sibling (e.g. ps_corpus_search) as the alternative, so it stops short of a 5.

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 closing phrase 'The "what do we already know" probe' implies this is a situational-orientation call to make before searching or running research. That is useful implied context, but there is no explicit when-to-use versus when-not, and no alternative is named.

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