web.feedback

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

No annotations are supplied, so the description carries the full behavioral burden. It does disclose a downstream effect ('linklog → prior'), implying the submission influences future link scoring, which is genuinely useful context. However, it says nothing about whether records are persisted, idempotent, deduplicated by URL, or what the call returns, and the jargon ('prior', 'linklog') is never defined.

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?

At two short sentences it is brief, but brevity here comes from compression into internal jargon rather than from precision. The purpose is not front-loaded, and the arrow notation 'A → B → C' forces the reader to decode a pipeline instead of reading a plain statement of function.

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 3-parameter mutation-style tool with no annotations, no output schema, and zero schema description coverage, the description should establish what is written, where, and under what conditions. It gestures at the feedback loop concept but leaves the agent unable to invoke the tool confidently, particularly regarding the role of 'query' and the effect of each label.

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 0%, so the description must compensate for all three parameters. Instead it only echoes the four label enum values already present in the schema and adds no meaning for 'url' (is it required to match a prior search result?) or for the optional 'query' (is it the originating query context?). This leaves the most semantically important parameter undocumented.

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 never states a verb or resource: it opens with the abstract phrase 'Pętla użyteczności' (utility loop) and an arrow chain 'used/opened/ignored/rejected → linklog → prior'. Only by cross-referencing the tool name web.feedback and the label enum can an agent infer this records a feedback label against a URL. The listed labels merely restate the schema enum rather than naming the action.

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 second sentence gives a rationale ('Bez tego system uczy się rozstrzygać linki, a nie pomagać'), which hints at why feedback matters, but there is no statement of when to call this versus siblings such as web.trace, web.eval, or web.stats. No preconditions, no when-not-to-use, and no named alternative are provided.

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