Neotoma

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

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: idempotency requirements, overwriting behavior between branches, and relationship creation. It doesn't fully cover all behavioral aspects like error conditions or performance characteristics, but provides substantial operational context.

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 description is appropriately sized but could be better structured. It front-loads the core purpose but mixes implementation details with usage guidelines. The chat-specific example is valuable but makes the description slightly dense. Every sentence earns its place, but the flow could be more logical.

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?

Given the complexity (10 parameters, no annotations, no output schema), the description does well to provide substantial context. It explains the tool's role in the system, provides concrete usage patterns, and addresses key operational concerns. The main gap is lack of output information, but overall it's quite complete for a complex storage tool.

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 60% schema description coverage, the description compensates well by explaining the semantics of key parameters through usage examples: it clarifies idempotency_key format, entity structure requirements, and relationship usage. While not covering all 10 parameters, it adds significant meaning beyond the schema for the most critical ones.

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 clearly states the tool's purpose with specific verbs ('store structured entities only') and distinguishes it from siblings by specifying it's for 'conversation- or tool-sourced data' and contrasting with 'file ingestion'. It explicitly differentiates from store_unstructured by focusing on structured data.

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 provides explicit when-to-use guidance ('Use when you already have entity objects and do not need file ingestion'), when-not-to-use guidance (contrasts with file ingestion), and mentions an alternative ('history via list_observations'). It also provides specific implementation examples for chat contexts.

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