invoicelens_ingest_document

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world. The description adds genuinely new behavioral facts: re-ingestion overwrites the prior version, doc_id is a content hash (which explains the idempotency), and what the response contains. It omits cost/time characteristics of embedding, which is the main operational unknown.

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?

Two short paragraphs, front-loaded with the pipeline and followed by the replace semantics. The trailing 'Returns the doc_id plus chunk counts by type' is slightly redundant given an output schema exists, but it is one short clause.

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?

With annotations covering safety/idempotency, a full output schema, and 100% parameter documentation, the description only needed to supply the write semantics and overwrite behavior, which it does. Missing only environmental notes such as index persistence or expected latency.

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%, so path, filename, collection and pdf_base64 are already fully documented with defaults and constraints. The description adds no parameter-level guidance, so the baseline of 3 applies.

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?

States a specific verb chain (parse, split, embed, store) on a specific resource (PDF into a FAISS index) with the chunking strategy named. It is immediately distinguishable from retrieval siblings such as search_documents and from extract_invoice, which does not write to the index.

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 the ingestion use case and covers the re-ingest case ('Ingesting the same file again replaces its previous version'), but never says when to prefer this over extract_invoice or which of path/pdf_base64 to choose in a given deployment. Usage is inferable rather than stated.

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