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

Beyond the annotations (readOnly=false, openWorld=true, idempotent=true, destructive=false), the description discloses two concrete side effects: the concept becomes live immediately with an empty page, and write tasks for it are queued on the common task list. It does not explain what happens if the id already exists, which matters given idempotentHint=true.

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?

Two sentences, front-loaded with the action and payload before the side effects. Every clause adds information: no restatement of the title and no filler.

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 single nested-object parameter with a 100% covered schema and no output schema, the description covers the payload shape and the key post-conditions. Remaining gaps are the undefined 'subject' field, the meaning of hard vs soft strength, and duplicate-id behavior under an idempotent hint.

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 schema is a single opaque object with additionalProperties {}, so the description carries real burden and does add meaning: 'lowercase id', 'name in one or more languages', and 'concepts already on the map' are constraints not present in the schema. It stops short of explaining what 'subject' is or what distinguishes hard from soft dependencies.

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 specific verb and resource ('Add a concept to the commons' shared map') and enumerates the payload it accepts (id, subject, names, dependencies). It is clearly distinct from read_concept, revise_needs, and propose_roadmap in kind, though it never explicitly contrasts itself with the roadmap-proposal sibling that also creates shared-map structure.

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?

Usage is implied rather than stated: an agent infers it should call this when a new concept must enter the map. The parenthetical '(concepts already on the map, hard or soft)' conveys a prerequisite that dependencies must pre-exist, which is useful, but there is no explicit when-to-use, when-not-to-use, or alternative-routing guidance.

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