find_flask_templates

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

No annotations are supplied, so the description carries the full burden, and it stays silent on whether the operation is read-only (implied by 'find') and on how results are shaped. It does earn credit for disclosing non-obvious behavioral detail the schema cannot express: the default-scope fallback chain from project config to scope_defaults.global to "main". That config-resolution behavior is exactly the kind of context an agent cannot infer from a null default in the schema.

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 purpose is front-loaded in a single sentence, and the supporting Args block is tightly scoped to the one parameter that needs explanation. The nested default chain is verbose but every clause adds information about a genuinely non-obvious resolution rule, so nothing is wasted.

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 an output schema present, the description need not explain return values, and it covers the only parameter's semantics well. The remaining gap is the array form of scope and the absence of any statement about read-only behavior, which matters slightly more given no annotations.

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%, so the description must compensate, and it largely does: it enumerates the three scope forms (main, all, namespace:name) and explains the default resolution order. The gap is the schema's anyOf allowing an array of strings, which the description never addresses, leaving the multi-scope form undocumented.

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 opening sentence gives a specific verb and resource pair: 'Find all Flask templates and render_template calls.' It distinguishes the tool from siblings like find_flask_routes and find_flask_blueprints by naming the distinct artifact type (templates plus render_template call sites). It doesn't explicitly contrast itself against those siblings, but the resource naming is specific enough to route correctly.

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?

There is no when-to-use or when-not-to-use guidance beyond the scope argument. Nothing tells the agent how this differs from find_flask_routes (which may also surface render_template invocations) or when to prefer it. The Args block describes a parameter, not usage conditions.

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