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

With no annotations, the description carries the full behavioral burden and does so unusually well: it discloses the admin requirement, the exact refusal code for agent seats (human_required), the console_required failure mode under decider=console, the audit label (org.automation.set), and an ~30-second propagation delay. It even points to where the current value is observable (schema_proposals in glian_status).

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 purpose in the first clause, then layers requirements, failure modes, and timing with no filler sentence. Some internal shorthand ('decider=console', 'land') costs a little readability, but every sentence contributes operational information.

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 one-parameter policy setter with an output schema present, the description covers purpose, authorization, refusal behavior, audit, and effect latency, and points to glian_status for the current value. It omits any note on reverting or on how in-flight held edges behave after switching modes, which would have made it 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 description coverage is 100% and the single enum parameter documents both auto and review semantics in detail, so the baseline is 3. The description adds no syntax or edge-case meaning for 'mode' beyond what the schema already says, and it slightly undersells 'review' by not mentioning it opens a schema_link_type review and holds edges.

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 opening sentence gives a specific verb and resource ('Set how distiller/curator link-type proposals land'), which is far more than a restatement of the name. It implicitly separates this policy tool from the sibling memory_ontology_link_type_set (which defines types) by scoping it to policy mode, though it never names that sibling. The word 'land' is slightly vague jargon for what is concretely a proposal-handling policy.

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 states prerequisites (org:admin) and caller restrictions (agent seats refused), and the enum in the schema carries the auto-vs-review choice, so usage context is implied. It never explicitly says when an agent should reach for this instead of memory_ontology_link_type_set, memory_write_policy_set, or review_policy_set. The 'like org_automation_set' clause is an analogy, not a routing rule.

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