gnosys_reinforce

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

Annotations only say readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description adds real substance by disclosing the side effect of every signal branch: useful increments reinforcement and resets decay, not_relevant records a routing miss without mutating the memory, and outdated only marks it for review. That both explains the non-idempotency hint and reassures the agent that two of three branches are effectively non-destructive.

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 effect of the tool is front-loaded in the first clause before the branch semantics and the sibling exclusion, which is the right ordering. The semicolon-chained enumeration of signal effects is dense but every clause carries distinct information; only the trailing repeat-behaviour note could be tightened.

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 4-parameter tool with full schema coverage and no output schema, the description covers what is needed: what changes per signal, what is returned, and when to choose the sibling. Minor gaps remain around projectRoot routing and whether the signal confirmation has any payload, but nothing blocks a correct call.

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 100%, so the baseline is 3, and the description earns above that by giving behavioural meaning to the signal enum values rather than restating the field. It adds nothing about context or projectRoot, which is acceptable since the schema already describes both.

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 first clause names a specific verb and resource ("Record usefulness feedback for one memory") and states the return ("signal confirmation"). It goes further by spelling out the effect of each of the three signal values, so the agent knows exactly what operation it is selecting without opening the schema.

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 names the alternative sibling explicitly ("Use gnosys_reflect instead to record an outcome memory, link evidence, and adjust confidence") and gives the condition that selects it. It also clarifies repeat behaviour ("repeated useful calls reinforce again"), removing the main ambiguity about calling this tool more than once.

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