aiworkhub_manager_needfix_markdown_preview

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

The annotations already declare readOnlyHint=true, so the description's 'MANAGER READ' adds no new safety context. It does not explain what 'bounded captured' means, how source_paths or follow_links affect behavior, or what the preview output contains.

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 a single front-loaded sentence with no wasted words, but its brevity creates ambiguity rather than clarity. It is concise but under-specified for an agent to act on confidently.

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 and readOnly annotation exist, but the description leaves substantial gaps: no parameter semantics, no usage context, and no explanation of the Markdown source or bounding behavior. An agent would likely need to inspect schemas or guess.

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 the description does not mention either parameter. follow_links and source_paths are completely undocumented, leaving the agent unable to infer their expected types or effects.

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?

It states a specific verb ('preview') and resource ('NeedFix candidates from Markdown'), but modifiers like 'bounded captured' are opaque and do not clearly differentiate it from siblings such as needfix_preview_convert or aiworkhub_manager_needfix_markdown_commit.

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 no guidance on when to use this preview versus alternatives like needfix_preview_convert, needfix_convert, or needfix_list. The 'MANAGER READ' prefix implies a read-only preview but does not explicitly route the agent.

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