add_document

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

With no annotations, the description carries the full burden and does well: it discloses that the element map is built by a background thread and can take minutes, that index and page images are available immediately, and that the auto-proposed MPN 'can be wrong'. Gaps remain around side effects (does it copy the file, dedupe an existing document, overwrite anything?) and any permission requirements.

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?

Front-loaded with what the tool does, then usage, then behavior, then next step – a sensible ordering. It is on the long side and the sentence about return values ('Gives the document reference, the pages, the size of the index and the state of the element map') partially duplicates what the output schema already states.

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 multi-step, slow, side-effecting ingestion tool this covers the essentials: async behavior, the timing of partial results, the empty-part fallback, and the follow-up call. Since an output schema exists, its brief return summary is not needed, and side-effect/dedup semantics are the one meaningful thing left unstated.

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 coverage is 100%, so baseline is 3, but the description adds genuine semantics beyond the schema: the consequence of omitting part (an approximate MPN proposal from the PDF text), the retry pattern with part, and where a valid path value comes from. It does not elaborate on role or variants, but those are already well documented in the schema.

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 and resource ('Add a PDF document to the store') and enumerates the pipeline it performs: copy/download, build index, build element map, link to part. This is clearly distinguishable from list_documents and from the read-only siblings like get_index or get_page_image.

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?

Gives an explicit trigger ('when list_documents does not find the datasheet'), acceptable URL sources (distributor tool, CAD symbol Datasheet field), and a follow-up rule: read the MPN from page 1 of the original, then call add_document again with part. It also routes the agent onward to project_add_part.

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