get_project_context

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

With no annotations provided, the description carries the full burden. It discloses that the tool walks up from cwd, parses symbols.json, classifies the environment from filesystem signals, and returns a payload. It also gives operational behavior like checking for token presence and instructing the agent to ask the user when next_step says so. However, it doesn't explicitly state whether the tool is read-only or has side effects, though 'Read' implies it.

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 well-structured with a main sentence, a section explaining return values in bullet points, and usage guidance in bold. It is somewhat long but every section adds value. Minor redundancy exists ('START HERE' and 'ALWAYS call this first' repeat similar guidance), but overall it is efficiently organized.

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 complexity and that an output schema exists, the description is complete. It enumerates all return fields with meanings, explains the environment classification, gives actionable next_step guidance, and covers authentication-related context. No important aspect of the tool's behavior is left undocumented.

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?

The schema provides only a 'cwd' property with a default and no description (0% coverage). The description fully compensates by explaining the meaning of cwd, its default behavior (MCP server's cwd), and when to pass an absolute path. This is exactly the kind of semantic enrichment needed.

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 clearly states the tool reads the current Symbols project context and is the starting point for any Symbols task. It names specific resources (symbols.json, filesystem signals) and explicitly distinguishes it from the sibling tool detect_environment, which it replaces.

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 description provides explicit usage guidance: 'ALWAYS call this first' for any Symbols-project task, and instructs to use it before auth-required tools like save_to_project, publish, push, and get_project. It also names the alternative detect_environment and explains when to use this tool instead.

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