nestor_tool_pending

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

Annotations declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, covering the safety profile. The description adds non-obvious behavior beyond annotations: deduplication by phrasing, chronological ordering (newest first), and the emptiness condition ('Empty when every routed intent has a sealed home'). This is exactly the kind of behavioral context an agent needs and can't infer from annotations alone. Minor deduction for not covering unsubscribe/auth behavior, which is contextually light for a read of app-scoped data.

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 sentences achieve maximum information density: the first labels and scopes the resource, the second details ordering and deduplication, the third explains the empty state. Every clause carries meaning. The only friction is the density of the 'teach-queue'/'sealed home'/'oracle learns' metaphor, which is charming but slightly cryptic for the first-time reader—a tradeoff worth noting, though the subsequent prose rewards the effort.

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 read-only, annotation-covered queue listing, the description thoroughly grounds the agent in what this tool is for and where it sits in the 'teach-queue' workflow. With no output schema present, the primary omission is any hint of what each item looks like (an object with an 'id'? a 'statement'?) or what 'seal' and 'reject' mean observably—two actions the description explicitly tasks the agent with enabling. The tradeoff: the state model is now so clear that matter feels minor. The description does everything except itemize the queue entries and their lifecycle outcomes.

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?

With schema description coverage at a critical 0%, the description bears full responsibility for parameter semantics, yet it says nothing directly about limit or app_id. It implies limit-style pagination via 'newest first' ordering and hints at app scoping through 'seal... home', but never bridges these to the actual parameters. An agent can infer from the 'limit' name + default that it bounds result size, but 'app_id' gets no semantic grounding—its role as a scoping key for the pending queue is entirely unexplained. For a tool whose description excels elsewhere, this is a clear semantic gap in the parameter contract.

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 states a concrete resource ('teach-queue: natural-language intents nestor_tole_route couldn't serve') with specific semantics: what the queue holds, its ordering (newest first), dedup behavior (by phrasing), and empty-state condition. It clearly differentiates from siblings nestor_tool_route and nestor_tool_seal by framing this as the intermediate review state in the workflow.

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 implies when to use it — 'intents nestor_tool_route couldn't serve... what a human should seal (or reject)' establishes the trigger condition of the routing workflow. However, this is implied through narrative rather than an explicit directive; there's no direct comparison to alternatives or stated conditions for when not to use it. The exclusion of siblings is ideally direct, not assumed from naming convention.

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