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

With no annotations provided, the description carries the full burden, and it delivers: it discloses the multi-step behavior (read from disk, upload, wait for chunking/indexing, report result) and the supported file types. It doesn't cover failure modes or side effects, but the core blocking behavior and outcome are transparent.

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 sentences with no filler: purpose is front-loaded, the operation sequence follows, and compatibility/outcome are stated last. Every sentence contributes information an agent needs.

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 three-parameter tool with no output schema, the description explains the full lifecycle and result. It doesn't detail the exact report shape, but 'reports the result' combined with the clear workflow is sufficient for correct invocation.

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 adds minor useful context by stating that 'PDFs and text both work,' which clarifies accepted file_path values, but the schema already documents parameter purpose and defaults adequately.

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 uses a specific verb and resource: 'Import a document into the Homestead Library.' It clearly distinguishes from siblings by framing this as the ingest operation, with 'The document becomes searchable via homestead_search' tying it to the search sibling without conflating them.

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 context is clear: use this tool when you need to add a document to the library and make it searchable. It doesn't explicitly name alternatives or exclusions, but the workflow description and searchability outcome make the intended use unambiguous for an agent.

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 present, so the description carries the full burden. It discloses the read-only nature via 'List' and describes the output contents ('packs, shelves, and every source with its publisher, licence and download size'), which tells the agent what to expect. It does not mention side effects, performance, or auth, but for a catalog listing that is minimal risk. The description is transparent enough.

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 sentences, zero filler. The first sentence states the action and output detail, the second gives a direct follow-up action. Key information is front-loaded, and every word earns its place. This is an exemplar of concise, well-structured tool documentation.

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 no-argument, no-output-schema, no-annotation tool, the description is complete. It explains what data will be returned (installable items with publisher, licence, download size) and why/when to call it. An agent has enough to decide to invoke it and to interpret the result without external documentation.

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 tool takes zero parameters, so the baseline is 4 under the rubric. The description adds no parameter-level semantics because there are none to describe. It does signal the output granularity, which indirectly helps the agent understand what it will receive without any required arguments.

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 ('List') and a clear resource ('what can be installed'), enumerating the exact contents (packs, shelves, sources with publisher, licence, download size). It also anchors itself against a sibling ('Call this before homestead_install'), which prevents confusion with the install workflow. This gives an agent an unambiguous picture of the tool's 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 description explicitly states when to call this tool: 'Call this before homestead_install to choose shelves.' That provides a clear temporal condition and a related sibling. It does not enumerate other alternatives (e.g., when to use homestead_search or homestead_categories instead), so it stops short of a full when-not matrix, but the core usage context is unambiguous.

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 provided, the description carries the behavioral burden and does disclose the read-only nature via 'List', and it reveals that results include safety cautions attached to shelves. It does not discuss error conditions or access requirements, but for a parameterless listing tool this is a reasonable level of transparency.

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 tight sentences accomplish everything: the first states the operation and its outputs; the second gives the immediate usage guidance. There is no filler, and the purpose 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 paramless listing tool, this description is complete: it names the output fields, flags the safety-caution element, and explains how the result should be used with sibling tools. Nothing an agent needs to select or invoke 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?

The tool has zero parameters and the schema covers 100% of them by being empty, so there is nothing the description needs to clarify. The baseline for zero-parameter tools is 4, and no additional parameter guidance is warranted here.

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 ('List'), a precise resource ('the library's categories'), and enumerates the exact output fields (slug, label, counts, safety caution). The closing sentence ties the tool to its siblings by explaining it supplies slugs for homestead_search and homestead_add, making its role unmistakable.

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 explicitly tells the agent when to call it: to pick a valid slug before using homestead_search or homestead_add. It provides clear context for the primary use case, though it does not enumerate when-not-to-use scenarios or list alternative tools for other needs.

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 provided, the description carries the disclosure burden. It accurately conveys that this is a read-only listing operation with optional category filtering, but it does not mention behaviors such as response format, pagination, ordering, or behavior for invalid or empty categories. This is acceptable for a simple list tool but not fully transparent.

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, front-loaded sentence with no filler. It communicates the core operation and the optional parameter clearly, and every word contributes to understanding.

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 tool with one optional parameter and no output schema, the description provides enough to make a basic call. It falls slightly short of complete because it does not clarify how this relates to homestead_search or homestead_catalog, nor what the returned document list looks like.

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 single 'category' parameter is already well documented. The description adds only the phrase 'optionally limited to one category slug,' which mostly restates the schema rather than providing new semantic meaning. Baseline 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 states a clear verb ('List'), a specific resource ('documents in the library'), and an optional scoping condition ('limited to one category slug'). It is easy to understand what the tool does, though it does not explicitly differentiate it from siblings like homestead_search or homestead_catalog.

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 does not say when to use this tool versus alternatives such as homestead_search or homestead_catalog. There is no when-to-use guidance, exclusion context, or mention of sibling tools, so an agent must infer the appropriate choice from the tool name and minimal wording.

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 present, so the description carries the full burden of behavioral disclosure. It does convey that the tool is a read-only health check reporting uptime and counts, but it does not state response/error behavior or explicitly confirm that it has no side effects. The verb 'Check' implies safety, but that is left implicit.

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?

A single sentence with no filler, front-loading the purpose and then enumerating the observed metrics. Every word contributes 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?

For a parameterless health-check tool, the description covers the main purpose and the data the agent can expect. It is slightly incomplete because it does not explicitly describe the success/failure output shape or differentiate from homestead_status, but nothing critical is missing for basic invocation.

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 tool has zero parameters and an empty input schema, so there is nothing for the description to add. The baseline of 4 applies because no parameter documentation is needed.

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 uses a clear verb ('Check') and identifies the resource ('library server') plus the specific data points returned (passages, documents, categories, uptime). It does not, however, distinguish itself from the sibling tool homestead_status, which seems to overlap substantially.

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 gives no guidance on when to prefer this tool over alternatives such as homestead_status or homestead_catalog. There are no exclusions, prerequisites, or contextual conditions, leaving the agent to guess which health/status-related tool to invoke.

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 of behavioral disclosure. It reveals the asynchronous nature by returning a job id and referencing polling, but it does not disclose potential side effects (e.g., overwriting the index), prerequisites beyond downloaded documents, permissions, or error conditions. This is a significant gap for an operation that rebuilds a search index.

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?

A single, front-loaded sentence that states the action, source, and result. No wasted words, and the key information (job id and polling) is included immediately.

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 zero-parameter tool with no output schema, it adequately covers purpose, return value, and next step (poll homestead_job). It could add a note about the operation being long-running or destructive, but the job id implies asynchrony, and the tool's simplicity makes it reasonably 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?

The tool has zero parameters and an empty input schema, so per the baseline, 4 is appropriate. The description adds context about what the rebuild operates on (documents already downloaded) but does not need to explain parameters since none exist.

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: 'Rebuild the search index from the documents already downloaded.' It clearly distinguishes this from siblings like homestead_search (which searches) and homestead_add (which adds documents), and it names the return value (job id).

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 context 'from the documents already downloaded' implies when it should be used, but there is no explicit guidance on when not to use it or alternatives. It does mention polling homestead_job as a follow-up, but that is a next step, not a usage condition.

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 fully carries the burden. It discloses that the tool returns immediately with a job id, that work takes minutes, and that the first index build downloads a ~2 GB embedding model – all critical operational details. This is exemplary transparency.

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 sentences with no waste: purpose is front-loaded, async behavior and polling follow, and the model download is mentioned last. Every sentence adds value.

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?

Fully adequate for a complex tool. It covers purpose, usage, async workflow, and a significant resource warning (2 GB download). It also states the return value (job id) despite no output schema. Nothing an agent needs 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 parameters are already documented. The description adds a useful pointer to homestead_catalog for shelf slugs but doesn't elaborate on pack or index beyond the schema. Baseline 3 is appropriate since the schema handles parameter documentation.

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 action (download and index documents) and resource (library), and clarifies its role as the initial setup tool ('set a library up from nothing'). This distinguishes it from sibling tools like homestead_add, which likely handle incremental additions.

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?

Provides explicit guidance on when to use it (setting up a library from nothing) and how to handle the async job (poll homestead_job until done). It doesn't explicitly name alternatives like homestead_add, but the context strongly implies it's for initial bulk setup rather than ongoing additions.

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 behavioral burden. It discloses that the tool is a polling operation and that statuses eventually reach 'done' or 'error', which is useful. However, it doesn't state whether the operation is read-only, what intermediate statuses may appear, or how errors are surfaced.

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 no wasted words. The purpose is front-loaded and the polling condition is stated directly. Every phrase earns its place.

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 simple one-parameter polling tool, the description is adequate: it names the job types, the polling behavior, and the terminal statuses. But without an output schema, it leaves the response shape and the source of job_id unstated, which are meaningful gaps for an AI agent.

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 0% and the description adds little about job_id beyond what the schema already shows. It implies the ID identifies a homestead_install or homestead_index_build job, but it never says where the job_id comes from or what format it takes, so the agent must guess or infer the source.

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 tool reports progress of a homestead_install or homestead_index_build job, and adds the polling behavior with terminal statuses 'done' or 'error'. This clearly distinguishes it from sibling tools like homestead_install and homestead_index_build, which start the jobs.

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: this is the follow-up polling tool for jobs launched by homestead_install or homestead_index_build, and instructs the agent to poll until a terminal status appears. It doesn't explicitly list when not to use it or name alternatives, but the intended usage is easy to infer.

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 at all, the description carries the full behavioral burden. It discloses that the search is offline, that results are sourced from a local corpus, that passages are returned verbatim, and that availability persists without internet. These are meaningful behavioral traits that an agent needs to know. It does not cover every possible detail, but for a read-only search tool it is transparent enough.

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 action and resource, followed by a concise explanation of what is returned and when to prefer it. The parenthetical list of topics is somewhat long but provides useful scope context. There is no filler or redundancy.

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 moderate complexity, three parameters, and no output schema, the description provides sufficient context for selection and invocation: what it searches, what it returns, and when it is preferred. It could mention category enumeration or sibling distinctions, but the schema already points to homestead_categories, so this is adequately 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?

The input schema already documents all three parameters with descriptions, including 'k' defaults/rangeable values and the 'category' slug semantics. Schema description coverage is 100%, so the description is not required to compensate. The only parameter-related phrase in the description is 'matching documents,' which is already implied by the schema, so no additional semantic value is added.

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 resource: 'Search the offline Homestead Library.' It further states that it returns 'matching documents with verbatim passages from the source texts,' which clarifies the exact output. It also differentiates the tool from general knowledge by emphasizing the local, offline nature of the corpus.

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 explicitly says to prefer this tool over general knowledge for 'practical homestead, emergency or preparedness questions' and gives the rationale: these are the user's curated documents and they work offline. It does not explicitly compare against sibling tools like homestead_categories or homestead_docs, so it stops short of a full 5.

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 behavioral disclosure burden. It discloses that the tool works with nothing running, returns a per-component check (corpus, index, embeddings, server), and includes a 'next' field with a fix. It stops short of explicitly stating it is side-effect free or covering auth/rate limits, but for a status check this is strong coverage.

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 sentences, each earning its place: purpose, sibling contrast and usage timing, and return shape. The description is front-loaded with the core purpose and 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 output schema, the description fully explains what the tool returns: a check per component and a 'next' field with a fix. It also covers when to call it and how it differs from homestead_health. Missing details (e.g., exact check value formats) are not needed for correct selection and invocation.

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 tool accepts zero parameters and the schema is empty, so description cannot add parameter meaning. Per the baseline rule for 0-parameter tools, a score of 4 is appropriate; the schema already covers everything.

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 ('Check whether this machine's library is set up and ready to search') and explicitly differentiates from the sibling homestead_health by noting it 'works with nothing running'. An agent can distinguish this tool from its siblings without opening 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?

The description gives explicit when-to-use guidance: 'call it FIRST when a search fails or when setting a library up'. It also names the alternative (homestead_health) and the differentiating condition ('unlike homestead_health this works with nothing running'), leaving nothing to inference.

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