structure_adviceDetect structural issues in a folder area—such as overly deep folders, empty folders, poor type grouping, or duplicate names—and get discussion points for planning fixes.
Structure problems of an area (too deep, empty, by type, duplicate names) to discuss.
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes |
Changes observed during successful MCP inspections.
v0.1.1Output schema / (root)Previous value: -{
- "properties": {
- "result": {
- "additionalProperties": true,
- "title": "Result",
- "type": "object"
- }
- },
- "required": [
- "result"
- ],
- "title": "structure_adviceOutput",
- "type": "object"
-}New value: +nullv0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that the description adds essentially nothing: it never says whether the result is a list, a narrative advisory, or a grouped report, nor whether 'to discuss' implies human-in-the-loop follow-up — a meaningful gap for an advice-oriented tool.
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?
It is short but not concise — a sentence fragment with a parenthetical list and an unclear infinitive tail. Brevity here comes from under-specification rather than disciplined editing.
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 read-only diagnostic tool with no output schema and an undocumented parameter, the description should explain the input's meaning and the shape of the result. It explains neither, so an agent must open the schema and guess at output format.
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% for the single required 'area' parameter, so the description must carry the load and does not. 'Of an area' implies scope but never says whether an area is a folder path, an ID, or a domain segment, leaving the only parameter underspecified.
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 fragment 'Structure problems of an area (too deep, empty, by type, duplicate names)' does convey the resource being inspected and enumerates the problem categories, but there is no clear verb — 'to discuss' is ambiguous about whether it detects, reports, or advises. An agent can roughly tell this is diagnostic rather than a mutation, but it cannot confidently separate it from siblings like find_duplicates or survey.
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?
No when-to-use, when-not-to-use, or named alternative is given. With overlapping siblings such as find_duplicates, find_similar, survey, and inventory, the description provides no routing signal for choosing this tool over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.