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.

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

Without annotations, the description discloses some behavior: it returns no key values, provides a note for missing keys, and indicates the sources of the distributor list. However, it omits whether the operation is read-only, what happens on errors, or any side effects.

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 somewhat run-on and includes awkward phrasing (e.g., 'give it to the user'), though it is not excessively long. It lacks a front-loaded summary of the tool's action.

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 presence of an output schema and full parameter documentation, the description covers the essentials but could be clearer about the tool's purpose and usage context. It does not leave critical gaps, but it is not fully polished.

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 single path parameter is fully documented in the schema, and the description adds no additional meaning about its role. With 100% schema coverage, the baseline of 3 is appropriate.

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 conveys that the tool reports configured distributors and whether each has an API key, but it is phrased as a noun phrase rather than a clear action verb. It does not explicitly distinguish itself from sibling tools like search_distributors or project_availability.

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?

No guidance is given on when to use this tool instead of alternatives. The mention of CLI commands explains how a user modifies the list, not when an agent should call this tool.

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

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

With no annotations, the description carries the full disclosure burden and does substantial work: it lists the fields returned per fact, warns that facts are not authoritative and must be checked against the source, and explains the non-obvious lookup behavior where a concrete MPN also surfaces its datasheet's facts. It never states rate limits or pagination, but the behavioral core is well covered.

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 the core action and the sibling reference, then the part/base-part nuance, then the output shape, then the verification caveat — a sensible ordering with no filler. The fourth sentence is a little dense, but every sentence adds information.

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 an unannotated, zero-required-parameter search tool with an output schema and full parameter coverage, the description supplies everything needed: scope, inheritance behavior, per-fact return fields, and the follow-up verification step. Nothing an agent needs in order to call it correctly is missing.

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 the baseline is 3; the description exceeds it by adding semantics the schema does not: that 'part' also searches the base part and that a concrete MPN pulls in datasheet facts. Query and document semantics are left to the schema, which already documents them thoroughly.

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 ('Find values that were read before'), names the sibling that creates them (save_fact), and distinguishes itself from raw-text searching by explaining that it searches saved facts across a part and its base part. An agent can tell what it retrieves without opening the schema.

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 a clear usage context (retrieving previously recorded facts, with or without a part filter) and closes with a workflow directive: verify important values against the original, then set state via set_fact_status. It does not explicitly say when to prefer search_text over find_facts, so the alternative-selection guidance is implicit rather than stated.

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

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

With no annotations, the description carries the burden and does disclose a key behavioral limitation: the text layer can lose structure for tables, figures, and formulas. It also indicates the returned content includes type, page, and region. It does not discuss permissions, error behavior, or side effects, but for a retrieval-style tool the disclosed limitation is substantive.

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?

Three short sentences, front-loaded with the tool's purpose and followed by the critical usage distinction. Every sentence adds value, and nothing is redundant.

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 is complete for a simple two-parameter retrieval tool. Output schema richness and full parameter documentation cover the structural details, while the description supplies the essential limitation and alternative-tool guidance an agent needs.

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%, and the schema already documents both parameters, including where document references and element IDs come from. The description reinforces the text-layer context but does not add parameter syntax or format details beyond the schema, 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?

The description states a specific resource and scope: the full text of elements from the text layer, including type, page, and region. It clearly distinguishes this tool from get_page_image by naming the content types each handles, so an agent can select correctly without inspecting schemas.

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 says to use this tool for headings and paragraphs, and explicitly routes table values, figures, and formulas to get_page_image because the text layer can lose their structure. That is a clear when-to-use and when-to-use-alternative rule.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses a key limitation for large documents and mentions included diagnostics like pages with no text layer or low-resolution images, but it does not explicitly confirm read-only behavior or other operational traits.

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 front-loaded with the core index content and then adds the large-document limitation, get_outline alternative, diagnostic pages, and starting guidance. It is dense but mostly every sentence carries useful information.

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 that an output schema exists, the description need not enumerate return fields in detail. It covers the tool's contents, a key limitation, the sibling alternative, and when to start here, leaving only minor operational details 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?

There is only one parameter and schema description coverage is 100%, so the schema already fully documents the document reference. The description adds no additional parameter meaning beyond what the schema provides, making the baseline score appropriate.

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 identifies the resource as a document index containing outline entries with pages, table/figure captions with page and position, and pages lacking text or having low-resolution images. It explicitly distinguishes this tool from get_outline by explaining that large documents only show top outline levels while get_outline drills into a section.

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 a clear usage cue: "Start here to find where the content is." It also names the relevant alternative, get_outline, for entries under a section, though it does not explicitly state when not to use this tool.

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

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

With no annotations, the description carries the burden and does well: it discloses the output granularity (one line per code), the field semantics, and an important edge case (scheme-only datasheets yield no list). It doesn't state what happens on empty/missing text layer or whether results are truncated, which keeps it short of a 5.

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 the resource and output shape, and each following sentence adds a distinct piece of value (field meaning, alternative route, verification caveat). Slightly dense across six sentences but no 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?

An output schema exists, so return values needn't be spelled out, yet the description still conveys the practical shape of results. Combined with the alternative-path guidance and verification caveat, nothing an agent needs in order to call it correctly and interpret the result is missing.

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?

Only one parameter (document) and schema description coverage is 100%, so the schema already explains accepted identifiers (SHA-256 prefix, numeric ID). The description adds nothing about the document argument, so the baseline 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+resource: extract the orderable codes of a datasheet from its text layer, emitting one line per code with code, page and line. It also tells the agent what those fields mean in an ordering table (package, packing, temperature, state), so the tool is distinguishable from generic text extractors like get_element_text.

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?

Explicitly frames the goal ('use it to find the concrete orderable MPN for the BOM'), names the exclusion case ('a datasheet that gives only a scheme of its codes has no list'), and routes to the alternative ('read its ordering information (get_page_image)'). It even adds a downstream caveat to verify the code with a distributor via search_distributors.

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

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

No annotations are provided, so the description must carry the load. It does disclose that results carry page numbers and that this descends below top-level index entries, which is real behavioral value, but says nothing about depth limits, empty results, or that it is read-only.

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 sentences with the purpose front-loaded and the usage condition second. Nothing is wasted and no clause is redundant with the provided schema.

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 output schema covers return values and the input schema covers both parameters, so the description only needs purpose and routing, both of which it supplies. A minor gap is the absence of fallback behavior when a section has no outline entries.

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% and both parameters, including the section-number format, are already documented there. The description only echoes 'one section' and 'document', adding no format or lookup guidance beyond the schema, so baseline 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 the resource precisely ('outline entries under one section of a document, with pages'), which tells an agent this is a scoped structural read rather than a full index. It implicitly distinguishes itself from get_index by describing the deeper per-section scope, though it never uses an explicit verb like 'retrieve'.

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 a concrete selection condition: use for a large document, when get_index gives only the top levels. That routes the agent away from get_index toward this tool. It does not say when to prefer get_index or get_element_text instead, so it stops short of explicit alternatives.

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

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

No annotations are provided, so the description carries the burden and does well: it states the image format, DPI range for element/caption/region, full-page resolution behavior tied to max_px, relative input cost, and the returned line with page, region, dpi, size, and image. It lacks permission or failure-mode details, but those are less critical for a read-only image retrieval tool.

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 short and front-loads the output type and supported scopes. Some sentences are fragmentary or slightly awkward, but there is little wasted content.

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 parameter count, full schema coverage, and absence of an output schema, the description provides enough context: it explains the return format, rendering behavior, and cost tradeoff between scoped images and full pages. Minor details such as error behavior are omitted but not essential for calling the tool correctly.

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 all six parameters are already well documented in the input schema. The description adds some context about max_px and the relative cost of full-page images, but does not provide additional parameter-level meaning beyond 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?

The description clearly identifies the resource and output: the original page content as a PNG image, covering an element, caption, region, or full page. It does not explicitly contrast itself with sibling tools like get_element_text, but the image-specific purpose is clear.

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 useful guidance on scope selection: prefer element, caption, or region because a full page costs more input, and use a full page when a table fills the page. It does not explicitly say when to choose this tool over text-based siblings, but the guidance for choosing image scope is clear.

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

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

With no annotations, the description carries the full burden and does disclose the most important trait: a large new document's map can take minutes to build, and the result self-reports incompleteness along with the workaround. It does not cover caching, permissions, or result-size limits, which keeps it short of a 5.

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?

Content is front-loaded — what is returned, the line format, ID reuse, then the latency caveat and fallback. It is dense but a couple of clauses (the region/coordinate explanation) could be tightened without losing meaning.

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?

An output schema exists, yet the description still usefully sketches the per-element line format, and it covers the non-obvious async/latency behavior with an explicit fallback path. For a read-only structural tool it is essentially complete, with only caching and size limits unaddressed.

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 all three parameters (document, page, all_elements) are already documented in the schema, including the document reference format and the fact that text elements are only counted unless all_elements is true. The description adds the ID/region output format but no additional parameter semantics beyond the schema, so baseline 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?

The description clearly states the resource (the structural map of one page: headings, tables, figures, formulas, captions) and exactly what each returned line contains (ID, type, region, text). It implicitly separates itself from get_element_text and get_page_image by explaining that the map's IDs are the inputs to those tools. A crisper leading verb would push this to a 5.

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 routes the agent: use the returned IDs with get_element_text and get_page_image, and if the map is not yet built, fall back to get_index, search_text and get_page_image with a page or region. That is a concrete when-to-use / when-not-to-use statement naming the alternatives.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it does disclose the return shape (file path plus embedded PDF resource), which is genuinely useful. It does not state that this is a non-destructive read with no project side effects, nor that the caller's client must support embedded resources, and the 50-page cap appears only in the schema.

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?

Three short clauses, no filler, and the usage condition is front-loaded right after the purpose. The opening is a fragment rather than a complete sentence, which slightly hurts front-loading clarity but wastes no words.

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 no annotations and no output schema, the description does just enough by describing what is returned (path + embedded PDF). It omits the safety profile of a read operation and any mention of client-side requirements for consuming the embedded resource, leaving meaningful gaps for a zero-annotation 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?

Schema coverage is 100%: the pages parameter documents the "3-5,8" syntax and the 50-page limit, and document documents the SHA-256-prefix-or-numeric-ID forms. The description adds no parameter meaning beyond the schema, which is the baseline 3 case.

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 identifies the resource and the output form precisely: the requested original pages delivered as a new PDF file, plus a file path and embedded resource. It falls short of a clean verb+resource statement (it opens with a sentence fragment) and never names the sibling it competes with, but an agent can tell what it produces.

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?

"Use it when your client can read a PDF" gives an explicit selection condition and implicitly routes non-PDF-capable clients elsewhere (get_page_image), which is real guidance. It stops short of naming the alternative explicitly, so the agent must infer the fallback rather than being told.

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

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

With no annotations, the description carries the full behavioral burden, and it does well: it discloses what each result line contains and that a concrete part also yields its base part's documents. It omits return ordering, error behavior, and whether the call is read-only, though that is strongly implied.

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?

Three compact sentences, front-loaded with the scope statement and then the output shape. Slightly awkward opening clause ('The documents in the store, or...'), but there is no 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 tool is simple, with one optional parameter and an output schema. The behavioral and output notes are sufficient for correct invocation, and calling out the 12-character reference used by other tools helps the agent link results. Only minor gaps remain: ordering and error cases.

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 the baseline would be 3, but the description adds real semantics the schema lacks: the base-part inheritance rule that governs what the part parameter returns. That is valuable beyond the schema's 'MPN or alias, case ignored' note.

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 states the resource (documents) and its two scopes: the whole store, or one part. It is distinguishable from siblings like list_parts and list_items because it names documents and the expected output. The verb 'list' is only implied by the title, not stated outright.

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?

Usage is only implied: you call it to see which documents exist, optionally narrowing to a part. No explicit guidance on when to prefer this over siblings such as get_index, search_text, or list_parts.

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

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

With no annotations, the description carries the full burden: it discloses the scope (whole document, not one page) and the exact per-item shape returned, which tells an agent this is a lightweight read-only inventory rather than content retrieval. It omits any note on size limits, pagination, or behavior on documents with no items.

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?

Three short sentences, front-loaded with the resource, then the row shape, then the usage hint. Minor waste in the opening noun-fragment, but every sentence contributes.

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 two-parameter read-only list tool with an output schema, this covers what it returns, its scope and when to reach for it. The remaining gap is guidance on next steps (fetching text or image once the page is known) and any volume caveats.

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 both the document reference and the kind filter (table/figure/caption, empty = all) are already fully documented in the schema. The description adds only the document-wide scope framing and no further meaning for kind or document.

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 the specific resource (tables, figures, captions of the whole document) and what each row contains (element ID, page, region, caption). It's clearly a document-wide inventory, which distinguishes it from page-scoped siblings like get_page_map or get_element_text, though it doesn't name them explicitly.

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?

"Use it to find a table or a figure when you do not know its page" gives a concrete triggering scenario and implicitly excludes page-known lookups. It stops short of naming the alternative tools (e.g. get_element_text, search_text) for the cases it excludes.

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

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

With no annotations, the description carries the full burden; 'list' implies a read operation, and it helpfully discloses the exact output shape ('one line for each part: "MPN (manufacturer): N documents"'). It omits whether results are paginated, how large the store may be, or whether the listing is scoped to the current project, so behavioral disclosure is partial.

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?

Three tight sentences: what it returns, the exact row format, and the alternative. Front-loaded with the payload and free of 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?

An output schema exists, so return values need not be explained, yet the description still specifies the row format. For a zero-parameter read tool with sibling routing included, nothing an agent needs in order to call it correctly is missing.

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?

Zero parameters, so the schema baseline of 4 applies and there is no parameter semantics to compensate for. The description adds no misleading parameter hints.

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?

Names a specific resource (parts in the store) and the exact data returned per row (MPN, manufacturer, document count), which is far more than restating the name. It also explicitly contrasts itself with list_documents, so an agent can distinguish the two without opening schemas, though the phrase 'the store' is never anchored to a concrete scope.

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 final sentence routes the agent to the correct alternative for document-level data ('list_documents gives the documents of a part'), giving clear selection context. It stops short of stating exclusions or prerequisites (e.g., whether a project must be loaded first), but the sibling routing is explicit.

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

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

With no annotations, the description carries the burden and does well: it discloses that datasheet-lens does not open these pages, that results are one line per site, and that finding a datasheet should feed into add_document. It stops short of stating failure modes (e.g. sites with no match) or latency/coverage caveats.

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?

Content is compact and the scope is front-loaded, but the telegraphic sentence fragments ('A datasheet that you find: add_document with its URL. Gives one line for each site.') make the flow choppy and the final line's meaning (one result row per site) slightly ambiguous.

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?

Output schema exists, so return structure needn't be explained, and the description still covers the essential agent workflow: search links, don't fetch pages, pass along or ingest into add_document. Only minor gaps, such as what happens on partial/no results, remain.

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?

Only one parameter, and schema coverage is 100% with the schema already advising 'best the concrete orderable one.' The description adds no MPN formatting or matching guidance beyond what the schema states, so baseline 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 ('Search links') and resource (links for a part), then enumerates exactly which categories and sites are covered (datasheet/price/stock vs. CAD symbol/footprint/3D). It implicitly distinguishes itself from the distributor and CAD-project tools by scoping to external link lookup, though it never names a sibling like search_distributors directly.

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?

Explicit trigger conditions are given: 'Use them when the store and the CAD project have no datasheet, and for the CAD files.' It also tells the agent what to do next — open a link with a web tool, hand links to the user, or call add_document with a found URL — which is unusually complete routing guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that this mutates project state and links documents in the central store, and that project_sync copies documents into the project folder. It does not cover duplicate handling, permission requirements, or failure modes.

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?

Three short sentences, front-loaded with the main action. The phrase 'the documents that the store links to it' is slightly repetitive but does not waste significant space.

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?

An output schema exists and the input schema is fully documented, so return values and parameter meanings are covered. For a mutation tool with no annotations, the description should do more to explain side effects, duplicate behavior, or how it relates to project_sync sequencing; as written it is adequate but not complete.

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 the schema already fully documents the seven parameters. The description adds only a general note about linked documents and the project_sync follow-up, with no parameter-level guidance beyond what the schema provides.

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 clear verb and resource: 'Add a part to the user project' plus linking documents from the store. It implicitly contrasts with project_update_part/project_remove_part by focusing on addition, but it does not explicitly name or differentiate those siblings.

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 tool is used when adding a part and its linked documents to a project, and notes that project_sync must run afterward. However, it gives no explicit when-to-use versus project_update_part, nor any when-not-to-use or prerequisites.

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

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

With no annotations, the description carries the burden and does reasonably well: it discloses that calls hit enabled distributors' official APIs, that output is one line per part plus warnings for specific failure conditions, and that missing-API-key notes may appear (implying auth/configuration dependencies). It still omits failure modes, latency, and what happens when no distributor is enabled.

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?

Purpose is front-loaded in the first sentence, followed by output shape and then the user-relay instruction. Four sentences, all informative; the closing sentence is an instruction rather than description but still earns its place by specifying how to surface warnings and key notes.

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?

An output schema exists, so return structure needn't be re-explained, yet the description helpfully summarizes it (one line per part, warning categories). For a single-optional-param read/report tool this is close to complete; only edge cases (no distributors enabled, API failures) are left unaddressed.

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% for the single 'path' parameter including the datasheet-lens.toml lookup rule, so the schema does the work. The description adds nothing about the path argument; baseline 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?

The description names a specific resource and scope: lifecycle state plus stock for each part of the user project at enabled distributors, with per-part warnings for obsolete/discontinued/missing/out-of-stock items. This is clearly distinct from siblings like distributor_status, part_links, or project_check, though the phrasing is a noun clause rather than a verb-first statement.

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?

Usage is implied ('the user project', enabled distributors) but the description never says when to pick this over distributor_status or project_check, nor any prerequisites such as needing configured distributors. The only explicit routing is a parenthetical pointer to search_distributors for API-key notes.

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

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

With no annotations, the description carries the full behavioral burden. It clearly states the tool is read-only ('It changes nothing') and describes some output behavior (conflict lines, missing/extra parts, datasheet requirements). However, it does not cover permissions, error conditions, or rate limits, leaving gaps for a tool with no annotations.

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 a single long paragraph with multiple clauses, mixing purpose and output details. Key information like 'It changes nothing' appears at the end rather than upfront. It is not excessively verbose but could be better structured for quick scanning.

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 tool's complexity (multi-faceted comparison) and the presence of a rich input schema (100% coverage) and an output schema, the description covers the essential behavior and output categories. It could mention prerequisites like the need for a project file, but overall it provides enough context for an agent to invoke it correctly.

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 the schema already documents both parameters thoroughly, including the flexible Value field and reference format. The description adds marginal context about how MPNs are found in Value fields and the datasheet requirement, but does not go significantly beyond 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?

The description clearly states a compare-and-reconcile operation between the project file and CAD parts, with specific output details (conflicts, counts, missing/extra parts). It distinguishes itself from siblings like project_sync or project_status by focusing on validation rather than mutation or status reporting. However, the phrasing is somewhat convoluted and not front-loaded.

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?

No explicit guidance on when to use this tool versus alternatives such as project_status, project_sync, or project_update_part. The description implies a verification scenario but does not state exclusions or conditions that would route an agent to a different sibling. Usage is left to inference.

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

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

With no annotations the description carries the full burden and mostly succeeds: it discloses the persistent exclusion that stops project_sync re-adding, that the local copy is deleted only when no part uses it, and that the central store is unaffected. It does not state permission requirements or whether the deletion is recoverable for the underlying file, which matters for a destructive operation.

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?

Four short sentences, each carrying distinct information, with the core scope stated first and lifecycle effects after. No filler; the telegraphic '(exclude)' phrasing is terse but still parseable.

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?

Output schema exists, so return values need not be described, and all six parameters are schema-documented. What remains thin is the guidance for a destructive mutation with no annotations — no note on permissions or irreversibility of the underlying file deletion when delete_pinned is true.

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 mpn, path, dry_run, manufacturer and delete_pinned are already fully documented; baseline is 3. The description adds only indirect meaning to 'document' via the re-add note, and says nothing extra about dry_run or the pinned-file interaction.

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?

Precise verb+resource ('Remove a document from the parts of the user project') with an immediate scope clarifier ('the parts stay') that separates it from the sibling project_remove_part. An agent can pick between the two without opening either schema.

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 clear context and names the reversal path ('project_add_part with this document adds it again') plus the sync interaction, so the agent knows what this tool is for and how to undo it. It stops short of an explicit when-not-to-use rule or a direct comparison to project_remove_part beyond the 'parts stay' clause.

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

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 unused copies are deleted, that pinned files survive unless delete_pinned is set, and that the central store is left untouched. It stops short of stating irreversibility or permission requirements, which would matter for a destructive operation.

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 core action and its scope come first, with the exception and the alternative following in logical order. Every sentence carries information, though the line-broken formatting makes it read less cleanly than it could.

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?

An output schema exists, yet the description still briefly notes what is returned (removed part, deleted and kept files), which is helpful rather than redundant. Combined with the delete scope and pinned rules, an agent has enough to invoke this safely; only explicit irreversibility or permission guidance is missing.

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 the baseline is 3, but the description adds real meaning by explaining the 'pinned' concept that delete_pinned depends on and by framing it as an exception to default behavior. It does not touch mpn, path, dry_run, or manufacturer, which the schema already handles.

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 ('Remove a part from the user project') plus the cascading scope ('delete its copies that no other part uses'). This clearly separates it from project_add_part and project_update_part without needing the schemas.

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?

Explicitly routes MPN changes to project_update_part, which is the main ambiguity an agent would face among the project_* siblings. It gives no explicit exclusion conditions for deletion itself, but the alternative is named and the pinned-file exception is stated.

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

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

With no annotations, the description carries the full burden and does so reasonably: 'It changes nothing' explicitly declares read-only behavior, and the shape of the report (one line per part, one line per document, possible leading notice about a newer release or LLM client restart) is disclosed. It does not cover error conditions (e.g., missing project file) or what happens when path points outside a project.

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?

Purpose is front-loaded and every sentence carries information about output structure or required agent behavior. The mid-sentence line wrapping and slightly informal phrasing ('A first line can tell about...') cost it a little, but there is no 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?

An output schema exists, yet the description still usefully summarizes the two line types and the special leading notice the agent must relay to the user, which is the main behavioral requirement. The remaining gap is the absence of any routing guidance to the overlapping project_* and list_* siblings.

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 the single optional path parameter is fully documented there, including the default and the datasheet-lens.toml lookup rule. The description adds nothing about the parameter, so baseline 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?

The description clearly states the resource (parts and documents of the user project) and what is reported (state of the copies in the project folder: missing/changed copies, new files, problems). It is less explicit about the verb and never distinguishes itself from closely named siblings such as project_check, project_sync, list_parts, or list_documents.

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?

There is no statement of when to use this tool versus project_check, project_sync, list_parts, or list_documents, which all appear to overlap. The only guidance is an output-handling instruction ('A first line can tell about a newer release... tell the user'), not call-site guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses multi-step mutations: adding documents, copying missing files, moving copies into subfolders, and importing PDFs, and it says the result reports changes and problems. However, it omits permissions, idempotency, broader overwrite behavior beyond the schema's restore parameter, and failure impact.

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 front-loaded with the core action and then explains the sync steps. It is somewhat dense and long, but the clauses about document linking, copying, moving, importing, and the project_add_part handoff each add useful information.

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 tool is a complex multi-step mutation and has an output schema, so return values need not be explained. The description covers the main workflow and the add-part fallback, but it lacks usage guidance against sibling tools and does not address prerequisites, permissions, or failure modes.

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 the schema already documents path and restore, including defaults and the replacement behavior for restore=true. The description does not add parameter-level meaning beyond the schema, so the baseline score 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?

The description states a specific verb and resource: synchronize the user project with the central store. It lists concrete operations such as adding linked documents, copying missing files, moving copies into layout subfolders, and importing new PDFs. It also differentiates part of its role from project_add_part by saying that project_add_part assigns proposed parts, though it does not distinguish itself from project_check or project_status.

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?

Usage is implied by the sync workflow, but there is no explicit statement of when to call this instead of project_check, project_status, or project_availability. The only routing clue is that project_add_part handles assigning a proposed part for a different file.

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

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

With no annotations, the description carries the full burden and does disclose the key side effects: the part stays in place in the toml, its documents are retained rather than recreated, and project_sync handles relocations caused by layout. It also states the return payload ('Gives the part and its documents'). It does not mention permissions, error/atomicity behavior, or what happens on partial conflicts (e.g. duplicate MPN with differing manufacturer).

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?

Purpose is front-loaded in the first clause, and the remaining sentences carry real information about preservation and sync. The sentence about project_sync moving a copy 'when the layout gives it a different subfolder' is slightly elliptical and takes a moment to parse, but nothing is wasted.

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 7-parameter mutation tool with an output schema and full schema coverage, the description supplies the crucial non-schema context: in-place semantics, copy preservation, and the sync interaction. Given the output schema exists, it need not describe return values in detail. The absence of any annotation coverage leaves error/authorization behavior unstated, which is the main remaining gap.

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 every parameter including the empty-means-no-change semantics and the category null/empty distinction is already documented in the schema. The description only restates the four mutable fields at a high level and adds no syntax, format, or edge-case guidance beyond that.

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 verb and object ('Change a part of the user project in place') and enumerates the mutable attributes (MPN, base part, category, manufacturer). It distinguishes itself cleanly from project_remove_part/project_add_part by contrasting in-place editing with delete-and-recopy.

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 names the sibling alternatives (project_remove_part, project_add_part) and explains why you would pick this one instead: the part keeps its position in datasheet-lens.toml and its document copies. It also points to project_sync as the follow-up for relocating a copy. There is no explicit 'do not use when...' exclusion, but the contrast gives a clear selection signal.

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

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

With no annotations, the description carries the full burden and does disclose meaningful traits: a new fact starts in the 'unchecked' state and the call returns a fact number used for later reference. It does not say whether duplicates are rejected or silently created, nor what permissions or failure modes exist, so it stops short of full transparency for a write operation.

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?

Four short sentences, front-loaded with the purpose before the workflow rule. The closing 'Gives the fact number' is slightly redundant given an output schema exists, but nothing else is wasted.

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 12-parameter write tool with a fully documented schema and an output schema, the description supplies the workflow context an agent actually needs: dedup discipline, initial state, and the returned handle. Only the failure/duplicate-handling semantics are 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 description coverage is 100%, so the schema already explains document, page, subject, value, model, and the optional fields. The description only echoes the 'source and model ID' intent already spelled out in the schema, adding essentially nothing beyond it. Baseline 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 and resource ('Save a value that you read from the original, with its source and your model ID') plus the downstream payoff ('a later session finds it with find_facts'). The pairing with find_facts makes it immediately distinguishable from read-side siblings like search_text or get_element_text.

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 workflow rule: check with find_facts before reading a value, and never save the same value twice. That is real when-to-use guidance and names the alternative tool. It does not address the boundary with set_fact_status or what to do if a fact already exists but is wrong.

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

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

With no annotations, the description carries the burden and does well: it discloses the NOT ORDERABLE marking of obsolete parts, the per-result source attribution, the requirement of a personal API key per distributor, the note-with-steps behavior, and the up-to-50 result cap. It does not mention rate limits or failure modes for a distributor whose API errors out.

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 the outcome (what a result contains), then moves to eligibility, key requirements, and fallbacks — a sensible order. It is somewhat long and the hard line breaks plus the imperative 'Give the note to the user' make it read like a handoff memo rather than a definition, but no sentence is pure 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?

An output schema exists, so return formatting needn't be restated; within that constraint the description covers the prerequisites (keys, config source), the degradation path (notes, then part_links), and the result semantics an agent needs to act on the output correctly.

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 already 100%, so the baseline is 3; the description adds meaning by explaining that mpn may be a base part whose concrete MPNs are enumerated, and that distributor enablement is driven by the project file or global configuration. That is genuine context beyond the field descriptions.

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 (search orderable parts at enabled distributors) and enumerates exactly what each result carries: lifecycle state, stock, prices, package, datasheet URL. An agent can tell this apart from part_links (link fallback) and get_ordering_codes without opening either schema.

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 concrete jobs to use it for (selecting the concrete MPN of the BOM, checking orderability) and spells out the fallback path when no API keys exist. It does not explicitly contrast with get_ordering_codes or project_availability, which is the one missing routing hint.

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

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

With no annotations, the description carries the full burden and does: it discloses result format, the element/region handle, that page headers/footers are suppressed unless repeated=true with a count on the last line, the cost advantage of region-targeted image reads, and the important caveat that 'the text layer can be wrong' so values should be confirmed on the original. That is more behavioral context than most definitions supply.

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, but the prose is loose and repeatedly broken mid-sentence by hard line breaks ('a\npart', 'their\nnumber'), which reads like unflattened wrapping and costs clarity. The header/footer note and the get_page_image advice are valuable but could be tightened.

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?

An output schema exists, and the description still summarizes the hit format and the accuracy caveat, so an agent can act without inspecting the schema. Annotations are absent, but the read-only nature is implied by 'find'; nothing critical is missing.

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 mode, repeated, max_lines and text semantics are already documented in the schema. The description only adds the downstream meaning of the element/region output and the header/footer suppression tied to repeated, so the baseline 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 and resource ('find a text in the text layer') and scopes it precisely: one document, or all documents of a part. It also previews the return shape (document ref, page, element or region, line). It does not explicitly contrast with the sibling get_element_text, which is the nearest look-alike.

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 a concrete use case ('find the page of a register, a parameter or a pin') and a follow-up path ('Give the element or the region to get_page_image'). It doesn't state exclusions, e.g. when list_items or get_element_text is the better entry point.

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

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

No annotations exist, so the description carries the full behavioral burden, yet it says nothing about reversibility, re-setting a status that was already set, permission requirements, or what happens to the note (the schema mentions notes are appended, not replaced). The mutation semantics of "set" are left entirely to inference.

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 sentences, front-loaded with the action, which is good. But the second sentence is ambiguous – "Gives the fact number and its new state" reads like parameter documentation yet could be mistaken for a return-value statement, and duplicates information already in the schema.

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?

An output schema exists, so return values need not be explained, and the three status values are covered by the schema. Still, for a state-mutating tool with no annotations the description omits the workflow context an agent needs: whether statuses can be reset, how note interacts with status, and what happens on an invalid fact_id.

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% – fact_id, status, and note are all documented, including the three allowed status values and the append behavior of note. The description merely restates "the fact number and its new state" and adds no format, constraints, or edge-case guidance beyond 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?

"Set the state of a saved fact" states a specific verb and resource, and the qualifier "after you compared it with the original" scopes it to facts already saved. It is distinguishable from save_fact/find_facts by the "saved fact" framing, though it never names those siblings explicitly.

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 phrase "after you compared it with the original" implies a trigger condition for calling the tool, which is more than nothing. However, no alternatives are named (e.g. use save_fact for new facts, find_facts to locate fact_id) and there are no explicit exclusions or preconditions.

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