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

Goes well beyond the readOnlyHint/non-destructive annotations: no recursion (so outputs/report.md only appears when outputs is listed), repo-linked projects listed from the branch plus local writes with .git/.venv/node_modules/__pycache__ excluded, nonexistent folder returns empty, out-of-project paths refused, and viewer-level access allowed. These are exactly the edge behaviors an agent needs before calling.

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?

Front-loads the verb, resource and return shape, then usage, then alternatives, then edge cases — good ordering with no filler. It is dense with multi-clause sentences (the repo/ignore-list sentence packs four ideas), which slightly taxes readability but every clause carries information.

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?

With no output schema, the description supplies the return entry structure { name, type, path } and covers recursion, filtering, failure modes, and permissions. An agent has everything needed to call this correctly and interpret results.

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 coverage is 100% and already documents all three parameters, including 'omit for the project root'. The description reinforces the path default ('the top level by default, or the folder given as path') and adds that the path must be a non-recursive folder scope, which is meaning beyond the schema, though it does not add syntax detail.

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 verb and resource ('List one folder of a Python project's code and files') plus the exact entry shape returned. It also explicitly separates itself from fastero_list_files and fastero_get_python_project, so an agent can pick it without opening sibling schemas.

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?

Gives a concrete use case ('Use it to find the path that fastero_read_python_file, fastero_write_python_file and fastero_ensure_python_entrypoint take') and names the two alternative list tools with the condition that selects each. Nothing is left to inference.

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