nayori_evaluation_request

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

Annotation Contradiction: annotations declare readOnlyHint=true, yet the description explicitly says 'with send:true it also posts it through Nayori's public evaluation relay' and reports '202 = queued', which implies an external side effect rather than a read-only operation. The added context about refusing preconditions and signing nothing is useful, but it cannot resolve the direct contradiction.

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?

Three dense sentences front-load the core action ('Build the exact JSON body') and then add only high-value constraints, side-effect behavior, response codes, and auth posture. No filler or redundant restatement of the schema.

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 complex tool with no output schema, the description covers the endpoint, request semantics, preconditions, response hints, and auth requirements. Minor gaps remain: the exact shape of a refusal/error result and the build-only return value are only implied, not stated.

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 60%, so the description needs to carry some parameter meaning, and it does: it ties acceptanceCriteria and evidence to on-chain commitment/deliverable hashing, and clarifies that send controls whether the body is actually POSTed. jobId and asset are less explained, but the tool-level text gives enough context for them to be understood.

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 names a specific verb and resource ('Build the exact JSON body for ... POST /v1/evaluations') and clearly distinguishes the build-only mode from the optional send mode. It also scopes the tool to a submitted job, so an agent can tell it apart from sibling tools like nayori_provider_submit_committed or nayori_submit_work.

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 gives clear invocation context: it is for a submitted job and only valid when a fresh read shows status 2, criteria match the on-chain commitment, and the deliverable matches recomputation. It does not explicitly name alternatives or exclusions, but the conditions effectively tell an agent when this tool is applicable.

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