ecosystem_mark_as_reference

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 reveals that the tool adds a tag and advances state, and that the repo becomes highlighted in searches. However, it omits details about reversibility, permissions, side effects for other tags or statuses, and whether the operation is idempotent. More behavioral context would improve transparency.

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 and front-loaded. It opens with the core action ('Stage 3 reference path — add lifecycle:reference tag + advance to referenced') and follows with usage guidance in a single compact paragraph. Every sentence earns its place without fluff.

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?

Considering the tool has 3 parameters, an output schema, and a clear domain context, the description is reasonably complete. It explains the lifecycle stage, the decision trigger, and the user-visible effect. It does not mention the output schema, but that is acceptable since the schema itself conveys that. Minor gaps in behavioral details lower the score below a 5.

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 input schema covers all three parameters (agent_id, confidence, deep_review_id) with descriptions, achieving 100% coverage. The tool description does not add any additional meaning or guidance beyond the schema, so the baseline score of 3 is appropriate.

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's action: mark a repo as a reference by adding a lifecycle tag and advancing its state. It distinguishes itself from sibling tools like ecosystem_mark_no_value by specifying the 'Stage 3 reference path' and the condition 'not integrated', making the purpose unmistakable.

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 explicitly says 'Use when the debate concludes that the repo is worth keeping as an architectural reference but not integrated', providing clear guidance on when to use. It also explains the consequence (highlighted in searches). While it doesn't explicitly name alternative tools for when the repo is integrated, the guidance is sufficient for correct usage.

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