telys_update

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false meaning mutation is expected, and the description adds contract-level behavioral detail: strict null id rejection with error message, persistence, and failure modes. It does not fully describe all side effects, but with annotations covering the safety profile the added detail is valuable.

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 dense but well-organized: main action, use case, required parameters, strict contract, and failure conditions all appear in four sentences. It is perhaps slightly redundant with schema text but each sentence earns its place and the core behavior is front-loaded.

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 write operation with no output schema, the description covers essential invocation context: required params, optional metadata behavior, persistence, and failure conditions. It would benefit from stating the return value or success response, but given the rich schema and annotations, the remaining gap is minor.

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 100% and every parameter is already documented with clear descriptions (e.g., 'one per id', 'strict: required', 'partition key is defaulted when omitted'). The description mostly echoes these details, adding only the strict error message and usage clarification. Baseline 3 is appropriate because the schema carries the parameter burden.

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 operation: replace vectors/metadata of EXISTING ids by re-embedding new texts, then persist. It differentiates from the sibling telys_upsert ('insert-or-replace instead') and uses precise scope ('existing ids', 'deliberate corrections to known rows').

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 gives an explicit when-to-use signal ('Use for deliberate corrections to known rows'), explicitly names the alternative for insert-or-replace (telys_upsert), and documents failure conditions (missing/null ids, collection not existing, length mismatch). This fully routes an agent to the correct tool.

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