declare_functional_relations

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

No annotations are provided, so the description carries the full burden. It discloses the key behavioral contract: new assertions supersede older ones automatically, and nothing is deleted. It does not discuss dataset-scoping or failure modes, but the central side effect is clearly communicated.

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 with no waste: the core subject is front-loaded, examples are provided, and the important supersede-and-not-delete behavior is included. Every clause earns its place.

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 simple two-parameter declaration tool with no annotations and no output schema, the description covers the essential invocation semantics and the important behavioral consequence. The only notable gap is the undocumented dataset parameter, but an agent can still call the tool correctly for the primary use case.

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 description enriches the 'names' parameter by defining what qualifies as a functional relation and giving examples, which the schema cannot convey. However, the 'dataset' parameter is entirely unexplained, and with 0% schema description coverage the tool does not fully compensate for both parameters.

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 uses a specific verb ('Declare') with a precise resource ('relation names that hold a single current value per subject') and concrete examples like current_owner and deployed_in. This clearly distinguishes it from assertion-level tools like remember or cross_connect and from other ontology tools like add_entity_type.

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 explicitly defines the target condition—relations where one current value per subject is desired—so an agent can recognize when this tool is appropriate. It does not name alternatives or state when not to use it, which keeps it just below the strongest guidance.

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