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

Annotations already set readOnlyHint=false and destructiveHint=true, and the description confirms this with 'May create, modify, or delete data through mFlow's agents.' It adds valuable extra context beyond annotations: the tool 'can take a while to respond (up to 60s) since it may call several tools internally before answering.' This latency and internal-tool-calling behavior is not captured in the annotations and helps the agent set expectations. No contradiction exists between description and annotations.

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 slightly longer than minimal but every sentence serves a purpose: it defines the tool's role, mentions semantic search and multi-step actions, warns about latency and potential data changes, and gives explicit routing advice. The core purpose is front-loaded, and the usage guidance appears early. While it could be tightened, the length is justified given the tool's flexible nature and the need to clarify when to use it versus structured alternatives.

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 catch-all tool with no output schema, the description covers the essential aspects: purpose, usage conditions, behavioral caveats (latency, data modification), and routing preferences. It names specific sibling tools as alternatives, which aids decision-making. The only minor gap is that it doesn't describe the output format, but given the tool's open-ended nature, that is not critical. The description is comprehensive enough for an agent to call it correctly.

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?

The input schema has 100% description coverage: every parameter (question, projectId, connectedAgent) has a clear description. The tool description itself does not add significant meaning beyond the schema—it mentions the question is natural language, which the schema already states, and it doesn't elaborate on projectId or connectedAgent beyond what the schema provides. Since the schema carries the parameter semantics fully, the description adds minimal value here, aligning with the baseline of 3 for high coverage.

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: to ask mFlow's AI assistant natural-language questions or requests for anything not covered by structured tools, including semantic search, multi-step actions, or ambiguous requests. It explicitly distinguishes itself from the structured siblings by framing itself as the catch-all fallback. This provides a specific verb ('ask'), resource ('mFlow's AI assistant'), and scope ('anything not covered by structured tools'), making it easy for an agent to understand when this is the right choice.

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 explicit guidance: 'Prefer a structured tool whenever one covers the request' and lists concrete examples (list_standalone_tasks, create_standalone_task). It then states the conditions for using this tool: 'when the request needs semantic search, spans several steps, or doesn't map to a single structured tool.' This is a clear when-to-use/when-not-to-use with named alternatives, leaving no ambiguity for the agent.

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