ps_research_followup

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 real side effects well – the sub-question tree is revised and the report re-rendered – which is more than most. It omits permissions/auth requirements, whether the revision is reversible or overwrites prior state, and the failure mode if the session does not exist.

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 tight sentence that is front-loaded with the core action ('push back on an existing session') before the effect clause. No filler, though it packs three behaviors into one sentence.

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 explained, and the mutation behavior is described. Still, for a no-annotation mutation tool the description leaves parameter meaning and sibling discrimination uncovered, so an agent cannot confidently route to it over ps_research_edit/answer.

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 there are 4 parameters, so the description must compensate. It adds meaning only for 'message' (narrow/expand/challenge), leaving session_id, config_path, and periscope_path entirely undocumented in both schema and description.

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 gives a specific verb ('push back on') and resource ('an existing session') and even clarifies the effect: the message can narrow, expand or challenge, and the sub-question tree is revised and report re-rendered. It is clearly a follow-up/refinement tool. However it never names or contrasts with close siblings such as ps_research_edit or ps_research_answer, so an agent must infer the boundary.

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?

'Existing session' and 'push back' imply this is only for continuing an already-started research session, which is useful implicit context. But there is no explicit when-to-use guidance, no exclusions, and no routing to the obvious alternatives (ps_research_edit, ps_research_answer, ps_research_step) that share this niche.

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