analyze_project

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

Annotations declare readOnlyHint=true, and the description adds substantial context beyond that: it runs on the server filesystem, rootDir defaults to server cwd, detects Tailwind v3/v4, and reports svg loader mode. This gives the agent a clear behavioral picture of a safe, local read-only probe. It doesn't exhaustively list every behavior, but it's well above baseline for an annotated read-only 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?

The description is dense but not bloated. It front-loads purpose, then usage guidance, then specific detection details. Each sentence adds distinct value (purpose, relationship to siblings, server-side execution, default, detection specifics). It could be tightened slightly, but overall it is well-structured and economical.

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?

The tool has no output schema, but the description compensates by listing what is detected (framework, language, styling system, component file extensions, svg handling, tailwindVersion, svg.mode). It also clarifies the operational context (server filesystem, no Figma, no file scan). For a simple probe with one optional parameter, this is sufficiently complete.

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% (one parameter, rootDir, fully described). The description adds meaningful extra semantics: 'rootDir defaults to the server cwd' and notes it is an optional override. This goes beyond the schema by clarifying the default and the scope of the parameter.

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 opens with a specific action and object: 'Detect the local project profile (framework, language, styling system, component file extensions, svg handling) by reading manifests and config'. It clearly distinguishes itself from siblings scan_components / component_map by positioning itself as the foundation and noting it is for 'inspection in isolation (no Figma, no file scan)'.

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?

Explicit usage guidance is provided: 'those tools run detection internally and return the same profile, so call this only to inspect detection in isolation'. It names the alternatives (scan_components / component_map) and states when not to use this tool, which fully addresses the when-to-use vs alternatives requirement.

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