observe

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains that observe() never supersedes or writes, only flags, reopens only when corroborated, treats already-seen grounds as echoes, and returns a specific response shape. This is far more transparent than the generic 'observe' label would imply.

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?

Though dense, the description is front-loaded with the core purpose and every sentence introduces a distinct operational fact: contradiction forms, corroboration, echo behavior, non-write guarantee, and return signature. The capitalization and monospace key terms add emphasis without adding filler.

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?

The description covers the tool's unusual semantics exceptionally well, including reopen thresholds, echo handling, non-writing behavior, and the return field list. However, with no output schema, the meanings of 'pending', 'need', and 'surfaced_prior' in the return object are left somewhat ambiguous, and the reopen_corroboration threshold is referenced but not defined.

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 schema has 0% description coverage, so the description must compensate. It does explain support as the grounds counted for corroboration, object='' as the value-obscuring revert case, and key as the attribute being contradicted. However, it never explicitly maps the 'text' parameter to 'the observation'—the connection is implied but not stated, which keeps this from a perfect score.

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 opens with a specific role—'READ-PATH review trigger'—and clearly defines the operation: feed an observation that contradicts a settled memory to reopen it for review after corroboration. It also distinguishes itself from write-path tools by stating 'NOT an authoritative write' and 'NEVER supersedes or writes,' and it names the downstream counterpart resolve_reopened(), making sibling differentiation easy.

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 states when to use the tool: 'Use it for contradicting evidence you don't want to act on blindly.' It also gives the conditions for action—corroboration requires >= reopen_corroboration distinct novel grounds—and clarifies that a lone stray restatement stays an echo and does not reopen. The non-write, flag-only behavior and the handoff to resolve_reopened() provide clear usage boundaries.

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