project_info

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

With no annotations, the description carries the burden of behavioral disclosure. It explicitly states error behavior ('Raises a clear error if dir has no package.json or no pebble block') and describes the inference logic (language detection from projectType and src/ layout). It does not explicitly state read-only, but the verb 'Summarize' strongly implies no side effects.

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 front-loaded with the main purpose, then lists return fields in a structured, comma-separated format, and ends with error conditions. Every sentence earns its place without unnecessary fluff. The formatting makes it easy to scan.

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?

Given the tool's simplicity (one parameter, no output schema), the description is fairly complete: it enumerates the full return payload and clearly states error conditions. It does not mention side effects, but 'Summarize' implicitly indicates a read-only operation. Missing explicit read-only confirmation is a minor gap.

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 parameter 'dir'. The description only indirectly clarifies that 'dir' is a directory containing package.json (from the error condition). It does not explicitly define the expected path format or that it should point to the project root. This is a partial compensation but not fully explicit.

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 verb-resource statement: 'Summarize an existing Pebble project from its package.json.' It also enumerates the exact return fields (name, displayName, uuid, etc.), making the tool's scope unmistakable and distinguishing it from siblings like project_set_meta or project_new.

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 context is clear: this tool is for reading/summarizing an existing Pebble project. It does not explicitly mention alternatives or when-not-to-use, but the phrasing 'existing' and the focus on package.json makes its role distinct. A brief exclusion (e.g., 'to create a project use project_new') would elevate it to a 5.

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