contribute_project

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

With no annotations, the description carries the full burden. It discloses important behavioral traits: private-by-default with optional public visibility, dynamic categories, and the auto-analysis mode for 'update hive' versus the interactive ask mode for 'add to hive'. It does not cover edge cases like overwriting or authentication, but the disclosed behaviors are substantial.

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 core purpose, then lists triggers, then explains the two distinct interaction modes. It also covers privacy and category flexibility without redundancy. It is slightly longer than necessary, but each sentence serves a role for the AI agent's routing and behavior.

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?

For a tool with 7 parameters, 3 required, no output schema, and no annotations, the description explains purpose, triggers, behavior, privacy, and category semantics. However, it misses prerequisites (e.g., the project hive must exist, requiring init_hive or init_project_kb) and does not describe what the tool returns after a successful contribution. These gaps make it less than fully 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%, so each parameter already has a description. The description adds some context by mentioning 'Stores solutions, patterns, pitfalls, architecture decisions' (relevant to query/solution/category) and 'Categories are dynamic' (relevant to category param), but this is minimal added meaning beyond the schema.

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 'Add knowledge to project hive', a clear verb+resource statement. It further lists content types (solutions, patterns, pitfalls, architecture decisions) that give concrete scope. However, it does not explicitly differentiate from sibling tools like contribute_solution or update_project_entry, so it stops short of a 5.

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 trigger phrases ('add to hive', 'update hive', etc.) and conditional behavior: for 'update hive' it says to analyze recent work and contribute automatically, while for 'add to hive' it says to ask what the user wants to store. This gives clear when-to-use context, though it does not mention exclusions or alternatives like using contribute_solution or init_hive.

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