share-knowledge

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

With no annotations, the description carries the behavioral burden and does disclose the key trait: the tool only generates a link, it does not submit anything itself, and the URL must be surfaced in the next user-facing reply. It says nothing about auth, failures, or repeated-call behavior, which keeps it short of a 5 given zero annotation coverage.

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?

Three sentences, front-loaded with the core action, then the trigger, then the critical output requirement. The emphasis is well placed, though the middle trigger sentence is somewhat long.

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?

There is no output schema, so the description must explain the return value -- and it does ('full magic link URL as a clickable Markdown link'). Combined with the contribution-collection workflow and the no-annotations behavior disclosure, an agent has enough to invoke it correctly, though nothing is said about error or edge cases.

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, but the description adds workflow meaning by naming the exact set of inputs to gather (title, author, content, tags) in the context of the contribution flow rather than just restating field names.

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 precise verb and artifact: 'Generate a pre-filled GitHub issue link so the user can submit a community contribution (project, tutorial, or pattern) to the repo.' It also enumerates the accepted contribution kinds, so an agent can distinguish this contribution-generating tool from the read-only siblings like get-doc and search-community.

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?

It gives explicit trigger conditions ('If the user has built or completed something useful with FeathersJS... proactively ask if they want to share; if they agree, collect title, author, content, tags and call this tool'). When-to-use and the prerequisite gathering step are both spelled out, leaving nothing to inference.

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