get_project_manifest

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Get the JSON manifest' and gives the parameter, but does not mention that this is a read-only operation (implied but not stated), what the manifest specifically contains beyond 'available files', any error conditions, or required permissions. The description adds little behavioral context beyond the tool name.

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 extremely concise: one sentence and a parameter line. It is front-loaded with the primary purpose and contains no fluff. Every sentence earns its place, making it easy to parse quickly.

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 is simple (one parameter, output schema exists), so the description covers the basics: purpose and parameter. However, given the presence of several sibling tools, it does not clarify when this tool is the right choice over others (e.g., list_project_texts or get_project_metadata). The output schema likely handles return values, but the usage ambiguity leaves a gap in completeness.

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 has 0% description coverage, so the description must compensate. It provides a concise parameter definition: 'project: ORACC project identifier.' This tells the agent the parameter's type (identifier) and domain (ORACC), which is sufficient for correct invocation. While it could include format examples, it covers the essential meaning well.

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 states a specific verb and resource: 'Get the JSON manifest listing available files for a project.' It clearly differentiates the tool's function (retrieving a manifest of available files) from siblings like get_project_metadata. The scope is explicit (per project), so an agent can immediately understand its purpose.

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?

No guidance is provided on when to use this tool versus the sibling tools (list_projects, get_project_metadata, list_project_texts, get_text, search_project). The description does not mention any conditions, exclusions, or alternatives, leaving the agent to infer the appropriate context. This is a significant gap given the overlapping sibling set.

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