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

With no annotations, the description must carry the full behavioral burden. It usefully discloses that output is written to disk and consumes no context window, and gives the default destination path. It omits important mutation semantics such as whether an existing file is overwritten, whether the directory is created, and what is returned to the caller.

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 core action and format, then the disk/context benefit, then the default path. Every sentence carries information and none 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?

There is no output schema and no annotations, so the description should be more complete for a write-to-disk operation. It covers destination and format but says nothing about overwrite behavior, error cases for an invalid section, or what the tool returns, leaving the agent partially informed.

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 three parameters are already documented in the schema, including the output_path default. The description restates the output_path default rather than adding new meaning (e.g. accepted path forms or failure behavior), 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 (export), resource (all pages in a section), and output format (single concatenated markdown file written to disk). It does not name a sibling tool or draw an explicit contrast, though 'zero context window cost' implicitly distinguishes it from the read_* 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 phrase 'zero context window cost' implies this is the tool to reach for when you want documents on disk rather than in the conversation, which is implied usage guidance. There is no explicit statement of when to prefer this over read_architect_page or get_section_summary, and no exclusions.

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 disclosure burden. It does usefully reveal the return contents (page/chunk/section counts, last run info, pending and failed URL counts), which signals a non-destructive read, but it says nothing about permissions, cost, freshness guarantees, or whether counts are cumulative versus from the last run.

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 names the operation first and then bullet-lists its contents in a compact enumeration. Every clause conveys distinct information about the payload, with 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?

With no output schema and no annotations, the description must describe the result, which it does by enumerating the fields an agent will receive. It is close to complete for a simple read-only status tool, lacking only finer detail such as time scoping of the run info and failed-URL counts.

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 per the baseline this dimension starts at 4. The description has no parameter semantics to add and correctly introduces none, describing only the result payload.

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 verb ('Get') and resource ('current status of the indexed database') and enumerates exactly what the status comprises: total pages, chunks, sections breakdown, last scrape run info, and pending/failed URL counts. This clearly separates it from the action-oriented siblings scrape_full and scrape_incremental, though it never names 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?

Usage is only implied: a zero-parameter 'get status' tool is obviously meant for checking indexing state, and the listing of pending/failed URL counts hints at post-run verification. There is no explicit when-to-use, no prerequisites, and no mention of alternatives such as the scrape siblings.

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. It usefully discloses the returned fields and implies a safe read via 'Get', but says nothing about pagination, response format, auth requirements, or rate limits, leaving meaningful gaps for a no-annotation 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?

Two tight sentences with zero filler: purpose and returned fields are front-loaded, and the usage hint follows. Every sentence 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 low-complexity, two-parameter read tool the definition is nearly sufficient: it covers purpose, return contents, and usage context. The lack of an output schema and absence of any annotation or behavioral detail around pagination/auth leaves a small but real 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%, with both 'section' and 'language' fully documented in the schema (including examples and the 'en' default). The description adds no parameter-level detail beyond what the schema already conveys, 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 names a specific verb and resource ('Get a quick overview of a section') and enumerates the returned data (page count, word count, page titles), which implicitly separates it from page-level siblings like read_architect_page_summary. It does not explicitly contrast itself with any sibling, so it falls short of the top tier.

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 usage context ('useful for orientation before exporting or reading individual pages'), which tells the agent when this tool is appropriate. However, it names no explicit alternatives or exclusions, so the routing decision between this and list_architect_sections/read_architect_page_summary is left partly 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?

No annotations exist, so the description carries the full burden. It does not state whether this is a read-only operation, whether pagination applies, or what the output structure looks like for multiple sections. Only the filter behavior is 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?

A single efficient sentence front-loads the main action and appends the optional filter. Every clause earns its place with no 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?

For a simple two-parameter list tool with no output schema, the description covers the basic purpose but omits return format, sorting, and pagination behavior. These gaps are modest given the tool's simplicity but leave some ambiguity.

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 parameters are already documented in the schema. The description adds only that the section filter is optional, which the schema also indicates. 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?

States a clear verb (List) and resource (indexed sections) plus what is returned (page counts and titles). It does not distinguish itself from siblings like get_section_summary or export_architect_section, which also touch sections.

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 mentions an optional section filter but gives no guidance on when to use this tool versus get_section_summary or search_architect_docs. No when-not or alternative routing is provided.

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 that the page must be indexed and that max_chars truncates output, but it does not mention authentication requirements, rate limits, error behavior for unindexed URLs, or explicitly confirm read-only/non-destructive behavior. Some behavioral context is present but incomplete.

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 three sentences, front-loaded with the core purpose, followed by parameter usage and an alternative suggestion. Every sentence earns its place with no redundancy or 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?

For a simple read tool with no output schema and no annotations, the description covers the main operation, the key parameter usage, and the relevant alternative. However, it omits context about authentication, error handling, and rate limits, leaving minor gaps for an agent to infer.

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 in detail. The description restates the max_chars behavior and implies the URL parameter, adding no meaningful semantics beyond what the schema provides. 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 specific verb (read) and resource (markdown content of a specific indexed Salesforce Architect page by its URL), clearly distinguishing it from read_architect_page_summary. An agent can immediately understand the tool's core function.

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 names the alternative (read_architect_page_summary) and the condition for using it (for a lightweight overview without full content), and instructs how to limit output with max_chars. This provides clear when-to-use and when-not-to-use 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?

No annotations exist, so the description carries the full burden. It does disclose the return shape (lightweight fields, ~500-char preview cap) and implies a read-only, cheap operation, but says nothing about permissions, freshness/staleness of the index, or rate limits. Adequate but not rich.

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 tightly written sentences with zero filler; the scope of the response is front-loaded and the usage hint second, which is the right ordering for a decision-oriented tool.

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 single-parameter read tool with no output schema and no annotations, the description supplies the return fields and the intended decision context, which is enough to call it correctly. Minor gaps remain around error behavior for unindexed URLs and what 'section' means in the payload.

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 single url parameter is fully documented in the schema as 'The exact URL of the page.' The description adds no syntax or format detail beyond that, so the baseline 3 for schema-covered parameters 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?

States a specific verb ('Get') and resource ('lightweight summary of an indexed page') and enumerates the exact payload (title, section, word count, headings, ~500-char preview). It contrasts cleanly with the sibling read_architect_page, which returns full content, so an agent can distinguish them 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 an explicit decision rule: use this to understand a page before deciding to read the full content, which implicitly routes to read_architect_page for the full read. It does not name the alternative tool directly or mention when-not to use it, so it falls just short of a 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?

With no annotations, the description carries the full burden and does disclose the critical destructive trait ('wipe all indexed data') plus the re-fetch/reindex pipeline. It leaves operational details unstated: expected duration, whether the run is blocking, and any auth/permission requirements for a full re-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?

Two tight sentences: the destructive pipeline first, the usage condition second. No filler and everything 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 two-optional-parameter, no-output-schema tool this covers the essentials, especially the data-destroying nature. The only real gap is that it never signals this is a heavy, long-running job, which an agent deciding between it and an incremental scrape would want to know.

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 (concurrency, language_filter) are fully described in the schema, including defaults and the enum values. The description adds nothing about them, so 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?

Names a specific operation ('Full refresh') and enumerates the three concrete steps: wipe indexed data, re-fetch the sitemap from architect.salesforce.com, and re-scrape/reindex every page. The 'full' framing cleanly separates it from the scrape_incremental sibling without needing to name it.

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 states when to use it ('initial setup or when you want a clean slate'), giving a clear triggering context. It does not, however, name scrape_incremental as the alternative for the non-clean-slate case, so the routing is implied via the name contrast 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 behavioral burden and does well: it discloses that already-indexed pages are only re-indexed when content actually changed, and that previously failed pages are retried. It omits write/mutation scope (it updates an index), permission needs, and runtime/long-running behavior, so it is 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?

A single sentence, front-loaded with the tool's identity and then the four pipeline stages in order. Every clause conveys distinct behavior; nothing is redundant or padded.

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 stateful scrape tool with no output schema, the description explains the operational lifecycle well enough to call it correctly. It could go further by indicating the returned result or how progress is observed (e.g., via get_scrape_status), but the core behavior is covered.

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% with only two optional params, so the schema already documents concurrency and language_filter fully. The description adds no syntax, default, or interaction detail beyond that, making the baseline 3 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 names a specific verb+resource ('Incremental scrape') and enumerates the exact pipeline: fetch sitemap, scrape new pages, retry failed pages, re-check existing pages. The 'incremental' framing, combined with 'not previously indexed', clearly separates it from the scrape_full sibling.

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 strong context for when this tool applies — for updating an existing index rather than building one — and implies the alternative is a full scrape. However, it never explicitly says 'use this instead of scrape_full when X', leaving the routing decision partly 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. It usefully discloses the scraping dependency and that results are ranked with excerpts, but says nothing about behavior when the index is empty, result freshness, or any rate/permission constraints.

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 with zero filler; purpose comes first, return shape second, and the operational prerequisite last. Every sentence carries 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 a read-only search tool with no output schema, the description covers what it does, what it returns, and the setup dependency an agent needs before calling it. Error/empty-index behavior is the only notable omission.

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 three parameters (query, section, max_results) are already documented in the schema. The description adds no format or syntax guidance for the query string or the section filter, 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 and resource ('Search the locally indexed Salesforce Architect documentation') and adds the return shape ('ranked results with excerpts'). The word 'locally indexed' separates it from the sibling read_architect_page tools, though the description 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?

Gives a concrete prerequisite: the database must be populated first via scrape_full or scrape_incremental, naming both sibling tools. It stops short of saying when to prefer this search over read_architect_page or get_section_summary for direct retrieval.

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