Share a project

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), it discloses the dry-run behavior, that preferences never leave the machine, that credentials cause refusal, that stale confirm tokens are refused, and that entries only go out on the next sync/consolidate. It also states unshare keeps already-sent content in the remote, which is a meaningful side effect. No contradiction with annotations.

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 dense but each sentence carries operational value: the dry-run protocol, refusal conditions, sync timing, and unshare semantics. It is not as compact as it could be, and the credential-rotation aside slightly interrupts the flow, but it remains well-structured and front-loaded with the core action.

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?

With no output schema, the description compensates by telling the agent what a dry run returns (ops_to_emit, skipped_preferences, confirm token), what can go wrong (credential, stale token), and when effects are visible (next sync or consolidate). The tool is fully callable from this description alone.

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 the baseline is 3. The description adds meaning beyond field names by explaining confirm is a token from the dry run and is omitted the first time, and by clarifying that space and confirm are ignored in unshare mode. This pushes it above baseline.

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 clear verb and resource: 'put one neuron into a team space, or take it out with unshare.' It distinguishes the share and unshare behaviors and contrasts with sibling crbro_space ('Spaces are managed with crbro_space'), so an agent knows exactly what this tool does and what it does not.

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 gives an explicit two-phase protocol: call without confirm first, show the user the dry-run report, get agreement, then call again with the confirm token. It also names alternatives for related cases: crbro_forget for credential handling and crbro_space for space management.

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