Declare Behavioural Link

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

With no annotations supplied, the description carries the full burden and does so well: it states the tool is mutating, that it creates no model version, that the link is re-checked on every read, that a counted link re-keys judgements which are queued and charged to the caller, and that unauthorized declarations are refused with 403 plus an escalation_id. That covers side effects, cost, and approval semantics beyond what any structured field provides.

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 purpose is front-loaded, then behaviour, then failure handling, then return shape – a sensible order. It is dense and a couple of clauses ('the judgements it re-keys are queued, charged to the caller') are compressed enough to require a second read, but there is little outright 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 mutating, policy-gated operation the description covers the things an agent most needs: side effects, the escalation path, and where to read the resulting links. It also restates the return shape and names proposals_hash as what a bulk acceptance uses now, which is helpful cross-tool context even though an output schema exists. The missing piece is guidance on direct declaration versus the proposal/acceptance workflow.

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 80%, so the baseline is 3. The description adds a little meaning by tying node_id to the values returned by get_behavioural_links and framing entity_id as the asset or trust boundary being asserted. It says nothing about server_version, the one undocumented parameter, so it does not fully compensate for the coverage gap.

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 gives a specific verb and resource: it declares the asset or trust boundary that a behavioural element or zone is, i.e. it creates a link between a node and an entity. That is far more informative than the title alone and is distinguishable from the read-side sibling it names (get_behavioural_links). The phrasing is somewhat indirect ('the asset or trust boundary ... is'), which costs it a point against a fully crisp statement.

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 useful operational guidance for the failure path (a 403 with an escalation_id must not be retried; report it and poll list_proposals) and points at get_behavioural_links to read the full set. What it never states is when to declare a link directly versus going through the proposal path (create_proposal / accept_behavioural_link_proposals are siblings), so the primary selection decision is left implicit.

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