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

The annotations declare destructiveHint=false, which in MCP semantics means the tool performs only additive updates, yet the description exposes a 'remove' { factId } action that deletes stored knowledge. That is a direct conflict with the declared safety profile; the description also says nothing about reversibility, permissions, or the side effects of 'refresh'.

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?

Front-loads the resource definition, then delivers an action-by-action payload table that is terse but information-dense; nearly every clause carries a parameter mapping or default. The telegraphic style is slightly compressed but wastes little space.

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 six-action, eight-parameter tool with no output schema and only minimal annotations, the description covers inputs thoroughly but says nothing about what 'list' returns or the shape of questions/answers, and never addresses the destructive 'remove' semantics. Adequate on the input side, incomplete on behavior and returns.

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 only 13% (just 'org' is documented), but the description compensates well: it defines the full action enum and maps payload parameters to actions (questionId/answer/topic/pageType for 'answer', text for 'add_note', factId for 'remove'), including the note that topic/pageType come 'as the question gave them'. Only the top-level types of the remaining params are left implicit.

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 names the resource (first-hand business knowledge: site-read facts and owner notes) and enumerates all six actions with their payloads, so an agent knows this is the knowledge-store tool with a set of read and write verbs. The opening clause is grammatically dangling ('which articles draw on'), which slightly muddies the framing, but the action inventory makes the purpose unambiguous.

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 states the default action ('list' (default)) and sketches each action's intent ('questions': what Seovyn would like the owner to answer; 'refresh': read the site again now), which is implied usage guidance. But there is no explicit when-to-use/when-not, and no routing to adjacent siblings such as seovyn_sources or seovyn_edit_article, leaving the agent to infer selection.

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