Santismm Knowledge — Harness Engineering, Agentic AI & Governance

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds some useful context ('from explicit assumptions', returned canonical_url should be cited), but it does not substantially expand on behavioral characteristics such as response structure or failure modes; the output schema covers those.

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 with no fluff: the first lists the computed outputs, the second states the intended use case and the two critical call-time constraints. The most important information is front-loaded and every clause 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?

Given the tool's complexity (14 parameters, output schema present, annotations present), the description plus schema is sufficient for an agent to call it correctly. It covers what is calculated, when to use it, and the currency/citation caveats. It could be slightly stronger by explicitly routing away from sibling calculation tools, but it is not materially incomplete.

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 does the heavy lifting for individual parameters. The description adds cross-parameter meaning by requiring all monetary inputs to be in the same currency, which is a constraint not encoded in the schema, and clarifies that all inputs are explicit assumptions rather than fetched data.

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 ('Calculate monthly operating cost... from explicit assumptions') and enumerates the exact output metrics (ROI, savings, break-even success rate). This clearly distinguishes it from sibling calculation tools like calculate_evaluation_sample_size and calculate_human_supervision_capacity.

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 use the tool ('Use this for an agent business case or scenario comparison') and gives practical usage constraints (same currency for monetary inputs, cite canonical_url). It does not explicitly name alternatives or state when not to use it, so it stops 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?

Annotations already establish readOnly, openWorld, idempotent, and destructiveHint=false, so the description does not need to cover mutation safety. It adds value beyond annotations by warning against interpreting zero observed failures as proof of zero risk and clarifying that the tool returns two separate sample-size calculations.

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 two sentences with no filler: the first states what the tool computes, and the second gives the use trigger plus a critical statistical warning. It is front-loaded with the most decision-relevant 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 the rich input schema, clear annotations, and the presence of an output schema, the description covers what the tool does, when to invoke it, and the most important interpretation pitfall. Nothing essential is missing 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?

Schema coverage is 100%, and every parameter has its own description with constraints or enums, so the schema carries the semantic weight. The description references failure rate, margin, and the estimate context at a high level but does not need to duplicate the schema's parameter details.

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 ('Calculate two different samples' for agent evaluation sample size) and distinguishes two concrete outputs: detecting at least one failure versus estimating the failure rate at a chosen margin. This level of specificity separates it from the sibling calculate tool (calculate_agent_economics) even without naming 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?

The description explicitly states when to use the tool: 'when a user asks how many tests are enough.' It also supplies a key interpretive caveat about zero observed failures. It does not formally state when not to use it or name an alternative sibling, but the trigger condition is clear and actionable.

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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar for additional behavioral disclosure is lower. The description adds a valuable caveat: 'the result uses averages and is not a queueing simulation.' This prevents the agent from over-trusting the output as a real-time simulation. No contradiction with annotations exists.

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. The first sentence front-loads the core outputs, the second gives the operational context, and the third states an essential limitation. 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 moderately complex 11-parameter calculation tool, the description provides purpose, use-case timing, and a critical methodological limitation. The output schema and fully described input schema cover the remaining details. An agent has enough context to select and invoke this 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 coverage is 100%, so every parameter is already documented with type, range, and meaning. The description adds no per-parameter detail, but it does summarize the output dimensions (FTE, cost, headroom/backlog) that tie the parameters together. This matches the baseline expected when the schema carries the descriptive load.

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 ('Calculate') and resource ('human supervision capacity'), then enumerates concrete outputs: review and escalation workload, required FTE, headroom/backlog, monthly labour cost, and sustainable case volume. This clearly differentiates it from sibling calculation tools like calculate_agent_economics or calculate_evaluation_sample_size. The purpose is unambiguous and immediately actionable.

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 use the tool: 'before production rollout to test whether the stated human-oversight model is operationally credible.' This gives clear contextual guidance. It does not explicitly name alternatives or state when not to use it, 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?

Annotations already cover safety (read-only, idempotent, non-destructive), and the description adds meaningful behavioral context by listing the contents of the response: request flow, reference scenario, KPIs, cost & scaling, and composed patterns/knowledge. It also communicates the prerequisite that a slug must come from prior search/list usage.

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 with no filler: the first states the action and result, the second gives the prerequisite workflow. The parenthetical list of contents is compact and informative without bloating the description.

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-resource fetch tool with a rich output schema and strong annotations, the description is complete. An agent knows what it retrieves, when to call it, and what prior step must happen first; the schema covers parameter details.

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 has 100% description coverage, including an example slug and a locale enum with default behavior. The description reinforces that the slug is the lookup key but adds little beyond the schema, so 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 states a specific verb ('Get') and resource ('one reference architecture by slug'), and enumerates what the returned architecture includes. This clearly distinguishes it from sibling list_architectures and search tools, which operate over collections rather than a single fetched item.

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 use this tool: after `search` or `list_architectures` has produced a slug. This gives a clear workflow and names the relevant alternatives, so the agent knows this is the follow-up fetch step, not a discovery 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?

Annotations already declare readOnlyHint, idempotentHint, and no destructive behavior, so the safety profile is covered. The description adds useful context about the response contents (Markdown-like body, metadata, licence context, canonical URL), but does not disclose additional behavioral traits such as error cases or availability 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?

Two sentences with no filler: the first states what the tool returns and the second gives the operational sequence. The key identifier concept ('by slug') is front-loaded, and 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 single-parameter, read-only tool with a rich annotation set and an output schema, the description covers the essential invocation context. It tells the agent what to expect in the response and how to obtain the required slug, leaving no critical gaps.

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 schema already fully documents the slug parameter with an example, so the baseline is 3. The description adds value by explicitly connecting the slug to the output of list_articles or search_articles, telling the agent where the value should come from rather than treating it as arbitrary input.

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 ('Get') and resource ('one complete essay'), and clearly distinguishes this from list/search operations by emphasizing a single essay fetched by slug. The phrase 'by slug' and 'one complete' make the tool's role unambiguous relative to siblings such as list_articles and search_articles.

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 use the tool: after list_articles or search_articles has returned the needed slug. It provides clear sequencing context, though it does not explicitly name alternatives or state when not to use this tool beyond the implied single-record scope.

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?

Annotations already cover readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds a genuine behavioral trait beyond those: the 'always present' guarantee that limitation and refuting-observation fields appear in every response, which shapes how an agent should interpret and report results. No contradiction with 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?

Two sentences with zero filler: the first front-loads the action, identifier format, and return contents; the second carries the usage guidance. The em-dash aside is purposeful because it emphasizes the always-present guarantee rather than decoration.

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 an output schema exists (return values documented) and annotations carry the safety profile, the description completes the picture: what the tool returns, how to identify the claim, and when to use it. Nothing an agent needs to correctly select and invoke this tool 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 description coverage is 100%, so both id and locale are already documented in the schema. The description's 'by id (HE-CLAIM-001) or slug' mirrors the schema's own example without adding new meaning, 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 ('Get one claim by id or slug') and enumerates the distinctive return content: statement, grounds, structured sources, what it does NOT establish, and the observation that would retire it. The title and description together differentiate it sharply from list_claims and the other get_* siblings, which return different resources.

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 two concrete when-to-use scenarios: citing the corpus honestly (because the tool surfaces limitations) and checking whether a measured result confirms or falsifies a claim. Clear context, though it does not explicitly name alternatives or state when-not-to-use it.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so no safety disclaimer is needed. The description adds behavioral context by specifying that the response contains scope, key requirements, implementable controls, checklist, and common pitfalls, which is useful beyond the annotations. It does not discuss not-found behavior, but the output schema and the explicit slug-precondition reduce that gap.

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, each earning their place: one defines the action and payload, the other gives the precise invocation context. No filler or redundant restatement.

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 get-by-slug tool with full schema coverage, read-only/idempotent annotations, and an output schema, the description is complete. It tells the agent what to expect inside the response, when to call it, and how to obtain a valid slug.

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 slug and locale with an example and default. The description adds only the operational hint that the slug should come from search/list_governance, which is helpful but not a substantial parameter-semantics contribution.

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-resource pair ('Get one AI governance unit by slug') and enumerates the payload contents (scope, requirements, controls, checklist, pitfalls). It also names the sibling flow (search/list_governance), so it is clearly distinguished from listing and search tools.

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 states when the tool is appropriate: 'Use this once search or list_governance has given you a slug.' This gives an actionable precondition and implicitly says not to call it before obtaining a slug from those 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful detail about the response contents (Markdown body, provenance, related ids) without contradicting any 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?

Two sentences with no filler; the core operation and return value are stated first, followed by a precise usage instruction. 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 simple read-only lookup tool with an output schema, rich annotations, and only two well-documented parameters, the description is complete. It covers what the tool does, what it returns, and when to call it in the larger workflow.

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 the `id` and `locale` parameters, including the id-or-slug semantics and locale default. The description reinforces the id format but does not add substantial new parameter meaning 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?

The description clearly states the tool retrieves one specific Harness Engineering Handbook chapter by id or slug, and specifies what is returned (full Markdown body, provenance, related ids). This gives the agent a distinct, actionable purpose among the many sibling get_* tools.

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 directs the agent to use this tool only after `search` or `list_handbook` has produced an id, which establishes the correct workflow and distinguishes it from discovery-oriented tools. This is clear when-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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds return-content context but does not disclose additional behavioral traits such as error cases, rate limits, or locale behavior beyond 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?

The description is two sentences with no filler. It front-loads the action and resource, then lists the useful content and the exact usage scenario, making every sentence earn 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 two-parameter read tool with a full input schema and an output schema, the description is complete: it states what is returned, how to address the resource, and when to choose it. No critical invocation details are 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 description coverage is 100%, so the schema already documents slug and locale. The description adds no parameter-specific meaning beyond confirming that lookup is by slug, which is sufficient given the high schema coverage.

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 ('Get one episode by slug') and enumerates the distinct contents: passage, narrative, competing theories, proponents/sources, confidence rubric, and FAQs. The 'episode' scope and the location-theory focus clearly separate it from siblings like get_homeric_place, get_homeric_route, and list_homeric_episodes.

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 when to use it: 'when the question is where an episode took place and who argued for it.' It does not name alternative tools or provide when-not-to-use guidance, 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?

While annotations declare readOnly, idempotent, and non-destructive, the description adds valuable behavioral detail: each identification carries its own coordinates, class, rubric, and sources, and crucially, 'a place the poem does not locate carries no coordinates at all'. This edge case goes well beyond the 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?

Two sentences, each earning its place. The first delivers the action and a compact list of returned data; the second gives the use case and a key edge case. No filler or repetition.

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 an output schema exists and annotations cover the safety profile, the description supplies the remaining needed context: when to use the tool and what data to expect, including the meaningful 'no coordinates' case. Nothing essential 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 for parameters is 100%: slug is described with an example and locale has an enum and default. The description only says 'by slug', adding no new parameter meaning beyond what the schema already 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 opens with a specific verb and resource: 'Get one place by slug', then enumerates exactly what is returned (identifications, coordinates, class, 0-12 rubric, sources, attested passages). This clearly distinguishes it from sibling tools like get_homeric_episode, get_homeric_route, and list_homeric_places.

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 states the intended use: 'Use this when you need to weigh the evidence for a location, or to cite it'. This gives clear context for when to choose this tool, though it does not explicitly name alternatives or describe when not to use it.

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?

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context: routes are returned side by side rather than merged, and each variant includes stops, chosen hypothesis, confidence rubric, and sources. This goes beyond what the annotations alone convey.

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 concise sentences with no wasted words. The core action and resource are front-loaded, followed by return-content details and a concrete use case. 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 simple single-route getter with full schema coverage, a rich output schema, and safety annotations, the description is complete. It explains what the tool returns, how variants are presented, and when to use it. Nothing essential is missing 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 slug and locale fully. The description adds 'by slug' but no additional parameter-level detail, so the baseline score 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 states a specific verb and resource: 'Get one route by slug'. It clearly describes what is returned (reconstruction variants, stops, hypotheses, confidence rubrics, sources) and differentiates the tool from sibling getters by emphasizing side-by-side comparison of rival reconstructions.

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 clear contextual guidance with 'Use this to compare rival reconstructions of a voyage', which tells the agent when this tool is appropriate. It does not explicitly name alternative tools or state when not to use it, 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?

The annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral nuance beyond that: it returns the full entry when no locale is given, and a single-locale body when locale is specified. This clarifies the tool's conditional output without contradicting 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?

Three short sentences with no filler, and the most important action and resource are front-loaded. Every sentence adds distinct value: what it does, the locale conditional, and the prerequisite workflow.

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 is present, the parameter schema documents both fields thoroughly, and the description covers the critical usage dependency on search/list_knowledge. Nothing necessary for correct invocation is missing for a simple read-only retrieve-by-slug 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%, so the baseline is 3; the description earns a 4 by explaining the semantic effect of the optional locale parameter ('single-locale body') rather than just naming it. It also reinforces that slug identifies which knowledge unit to fetch.

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 one knowledge unit by slug') and explains the conditional return behavior, clearly distinguishing it from list_knowledge and search. The title reinforces the resource type, so an agent can tell this from sibling get_* tools 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?

It explicitly states when to use the tool: 'Use this once search or list_knowledge has given you a slug.' This gives clear retrieval workflow context and implies it is for fetching an individual known item rather than searching or listing.

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 annotations already declaring readOnly, idempotent, and non-destructive behavior, the description adds meaningful context about what the response will contain and notes the conditional executable endpoint. It does not overload with safety claims but supplies useful behavioral detail beyond the structured 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?

Two sentences carry the essential information with no waste: what the tool returns, when to call it, and which sibling tool to prefer for formula computation. The most important scoping is front-loaded in the first sentence.

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 single-parameter fetch tool, the description fully equips an agent: it names the resource, the lookup key, the included content, the conditional endpoint, and the appropriate usage sequence. The presence of an output schema removes the need to describe return fields further.

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 the slug parameter with an example. The description adds no new parameter semantics beyond saying 'by slug', but that is acceptable since the schema covers it completely.

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 ('Get one Lab by slug') and enumerates the payload contents: formulas, assumptions, related SANTISMM content, and executable endpoint when present. It clearly differentiates from list_labs (listing) and calculate_* tools (computing formulas) among the sibling set.

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 instructs when to use this tool: 'Use this after list_labs or search_all'. It also names the alternative category ('the named calculate_* tool') and directs agents not to reimplement published formulas, giving clear routing guidance relative to 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns a map with specific contents, but since an output schema exists and there are no side effects, the description does not go beyond what annotations and schema already establish.

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 begins with the key directive 'Get the complete MCP map — start here' followed by a compact list of contents. Every word contributes meaning, with no wasted elaboration.

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, read-only, idempotent tool with an output schema, the description fully covers what the agent needs to invoke it correctly. The scope of the returned map is described succinctly and completely.

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, so the description carries no parameter burden. The baseline for a no-parameter tool is 4, and the description appropriately stays silent on inputs.

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: 'Get the complete MCP map' and explicitly lists what it returns (five-domain core, surfaces, tools, identifiers, citation rules, languages, licence, bulk-ingest URLs). It clearly differentiates this umbrella tool from the entity-specific get_* and list_* siblings by framing it as the comprehensive starting point.

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 'start here,' which tells the agent this is the intended entry point for orientation. It does not name alternatives or state when not to use it, but for a zero-parameter overview tool the directive is clear enough.

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?

The annotations already declare the read-only, idempotent, non-destructive safety profile. The description adds useful behavioral context by identifying what content the response includes, which goes beyond the annotations and 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?

Two short sentences cover both what the tool does and when to call it. There is no filler, and the primary purpose is front-loaded before the usage note.

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 get-by-identifier tool, the description, combined with full parameter schema, annotations, and an output schema, is complete. It gives the required workflow context and enough about the return payload to set agent expectations.

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 both `slug` and `locale`. The description mentions retrieving by slug but adds no additional meaning beyond what the schema provides, so 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 states a specific verb and resource: 'Get one Enterprise AI pattern by slug'. It also names the included content areas (problem, solution, KPIs, failure modes, lessons), making it clear what the tool returns and distinguishing it from listing or searching tools.

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 use this tool: after `search` or `list_patterns` has provided a slug. This is clear usage context, though it does not spell out formal exclusions for sibling get_* tools.

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?

Beyond the readOnly and idempotent annotations, the description discloses that results include both edge directions and relationship types, which is meaningful behavioral context. It does not mention potential size or pagination behavior, but the output schema covers return structure.

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 with no filler: the first defines the operation and output, the second gives usage guidance. The main behavioral statement 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 read-only one-hop traversal with complete parameter schema, an output schema, and safe annotations, the description provides all necessary selection and invocation context. Nothing important for correct use 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 description coverage is 100%, so the description does not need to document individual parameters. 'Given a unit' and 'neighbours' maps coherently to the domain/slug start point, adding minor semantic context over 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 states a specific operation: traverse the knowledge graph from a starting unit and return its outgoing and incoming neighbours with relationship types. This clearly distinguishes it from sibling get_* tools, which retrieve individual units rather than graph adjacencies.

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 advises using this tool after a get_* call to widen an answer with adjacent units, giving a clear context of use relative to the retrieval family. It does not spell out explicit when-not-to-use exclusions, 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?

Annotations already establish read-only, idempotent, and non-destructive behavior, so the description carries little additional safety burden. It adds useful scope context by stating that the tool lists all architectures and which fields are included, which is sufficient for a simple list 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 description is two sentences with no filler: the first states the operation and returned fields, and the second gives browse-vs-search usage guidance. 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 straightforward list operation, the description, schema, annotations, and output schema together cover everything an agent needs: operation, returned fields, locale behavior, safety profile, and routing to the correct sibling. Nothing material 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 input schema has 100% description coverage for the single optional locale parameter, so the parameter is already fully documented. The description adds no parameter-level details, but none are needed given the schema's completeness.

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-resource pair ('List all reference architectures') and enumerates the returned fields (id, slug, category, name, summary, provenance), making the operation unambiguous. It also distinguishes the tool from search by positioning it for browsing a known catalog rather than lookup by use case.

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 instructs the agent to use this tool to browse blueprints and to use the search tool when a use case rather than a name is available. This is clear and actionable routing guidance among the sibling tools.

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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond annotations: the exhaustive 'every' scope, the specific site, and the returned metadata fields. Minor gaps such as pagination or ordering are not significant for this low-risk read 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 sentences with no redundant words. The first sentence front-loads the action, scope, and output fields; the second provides routing guidance. 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?

Given the tool's low complexity (one optional parameter, output schema present, read-only annotations), the description is sufficient for an agent to select and invoke it correctly. It also distinguishes itself from the relevant sibling 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?

The input schema already fully describes the single optional `locale` parameter with an enum and a clear description ('Restrict by language'). Schema description coverage is 100%, so the description does not need to add much; it introduces language as an output field but not the parameter semantics, which is acceptable.

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 ('List'), a precise resource ('every long-form essay published on articles.santismm.com'), and the returned fields (language, dates, topics, canonical URLs). It clearly differentiates from search_articles and other sibling list tools.

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 when to use this tool ('Use this to browse the essay catalogue') and when to use an alternative ('use search_articles when you have a topic rather than a slug'). This gives an agent unambiguous 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context about what the list contains (epistemic status, confidence, underpinned units) and characterizes the epistemic ladder, which goes beyond the structured fields.

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, no filler. The core purpose and taxonomy are front-loaded, followed by a practical usage tip and a filtering hint. 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?

Given the tool's moderate complexity, an output schema exists, annotations cover the safety profile, and parameters are fully documented. The description supplies the conceptual context of the epistemic ladder and a concrete use case. Minor missing details like pagination or ordering are not critical for a list tool with an output schema.

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 coveage is 100%: both locale and claim_type have descriptions and enums. The description adds only the hint about filtering by claim_type, which references the parameter but does not add substantial new semantics beyond the schema. 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 uses a specific verb ('List'), a clear resource ('load-bearing claims of the corpus'), and enumerates the epistemic tags, confidence, and underpinned units. This makes it easily distinguishable from the singular get_claim and other list_* 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?

It provides a clear use case: 'Use this before quoting the handbook to know whether a statement is evidence, a reading of the industry, or a position taken.' It implies an alternative (quoting the handbook directly) but does not explicitly name sibling tools like get_claim as the alternative for a single claim.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope context about what is being listed, but does not add behavioral details beyond that, such as pagination, ordering, or locale effects. With annotations present, a 3 is appropriate.

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 two sentences with no wasted words. The first sentence front-loads the action, scope, and return fields; the second provides routing guidance. The parenthetical examples are informative rather than 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?

For a simple, optional-parameter list tool with an output schema and comprehensive annotations, the description is complete. It tells the agent what is returned, what the tool is for, and when to pick an alternative. The output schema handles return structure, and annotations handle safety guarantees.

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 only parameter, locale, has 100% schema description coverage including an enum of valid languages and a default. The description does not need to repeat this. The baseline of 3 applies because the schema fully documents the parameter semantics.

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: 'List all AI governance units', enumerates the categories and examples (regulations, standards, frameworks, playbooks, EU AI Act, ISO 42001), and specifies the returned fields. It differentiates from the sibling `search` tool by clarifying that browse is for regulations/standards while search is for an obligation or control.

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 use this tool: 'Use this to browse the regulations and standards'. It also names the alternative `search` and the condition for choosing it: 'use `search` for an obligation or control'. This gives clear 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?

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful context about the corpus and chapter scope, but does not disclose much additional behavioral detail beyond the basic listing behavior. This is acceptable given the strong annotation 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?

The description is front-loaded with the core action and resource, followed by useful corpus context and a clear usage instruction. The enumerated topic list is somewhat long but adds helpful context about what the handbook covers, so it 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, read-only listing tool with one optional parameter, a full output schema, and strong annotations, the description is complete. It states what the tool does, what it returns conceptually, and when to use a different 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?

The schema fully describes the single optional `locale` parameter, including its enum values and default behavior, so the description does not need to add parameter details. The description's mention of chapters and search routing provides context but not parameter-level semantics.

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: 'List the Harness Engineering Handbook chapters'. It also clarifies the scope and nature of the tool by describing the corpus and what the result represents, distinguishing it clearly from related list/get/search 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 gives explicit guidance: use this tool to see the chapter map, and use `search` when the user has a topic rather than a known chapter. This directly helps an agent choose between list_handbook and search 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?

The annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds valuable behavioral context by disclosing that the tool lists ALL episodes, returns them in reading order, and includes passage, places, and locatability — information not implied by the annotations alone.

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 with no filler. The first sentence states scope and output content; the second sentence gives routing guidance to the sibling tool. All information is front-loaded and each 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?

Given this is a simple read-only list tool with one optional parameter and an output schema, the description fully covers what an agent needs to know to select and invoke it correctly. It explains scope, ordering, content, and the path to more detailed episode information.

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 only parameter, `locale`, has full schema coverage (100%) with a clear description and an enum of allowed values. The tool description adds no additional parameter semantics, but the schema already carries the full meaning, so 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 states a specific verb ('List'), a clear resource ('every episode of the Iliad and the Odyssey held in the atlas'), and the exact attributes returned (passage, places, locatability). It also distinguishes itself from the sibling `get_homeric_episode` by framing this as the episode-finding tool rather than the deep-dive tool.

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 'Use this to find the episode you want' and directs the agent to `get_homeric_episode` for theories and sources. This gives a clear when-to-use and points to the relevant alternative without ambiguity.

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?

Annotations already cover the safety profile (read-only, idempotent, non-destructive), so the description needed to add interpretive context — and it does. It defines the four identification classes with criteria, explains the 0-12 confidence rubric as four 0-3 sub-scores, and adds an important caveat: confidence is 'an editorial judgement, not a probability.' That caveat prevents a genuine misinterpretation of the returned data.

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 routing guidance, then domain definitions. The description is dense but every block earns its place — the class definitions and confidence rubric are essential context an agent would otherwise lack. Slightly long, but the length is justified by the domain complexity.

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 tool (one optional parameter, output schema present, annotations covering safety), the description covers the critical semantics: what the data means, how confidence is computed, and how to drill down. Minor gaps remain — pagination, ordering, and whether locale affects returned place names — but these are non-critical for a browse-all tool backed by an output schema.

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 only parameter (locale, an enum with a documented default) is fully described in the schema. The description adds nothing about locale, but it doesn't need to — the baseline of 3 applies when the schema carries the full documentation burden.

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 opening sentence names a specific verb ('List'), a precise resource ('every place in the Homeric Atlas'), and the exact fields returned (identification class, confidence score, competing identifications count). It is immediately distinguishable from its siblings — both the other list_homeric_* tools and get_homeric_place — because it names the detail tool as its complement.

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 routing guidance: 'Use this to browse the atlas; use `get_homeric_place` once you have a slug.' This tells the agent exactly when to choose this tool over its sibling and when to switch. No inference is required.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral detail about the response including rival reconstructions with separate scores, but it does not go deeper into data provenance, pagination, or other runtime behavior. This is 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 sentences with no filler. The purpose and key detail are front-loaded, and the usage guidance follows naturally. 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 read-only list tool with one optional locale parameter, an output schema, and safety annotations, the description is complete. It tells the agent what the tool returns, that scoring is included, and when to call it before fetching a specific route.

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 only parameter, 'locale', is fully documented in the schema with its enum, meaning, and default value (schema coverage 100%). The description adds no parameter-specific information, so the schema carries the full burden. 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 verb ('List') and resource ('reconstructed itineraries'), and adds a distinguishing detail: rival reconstructions are scored separately. This clearly differentiates it from sibling tools like get_homeric_route, list_homeric_episodes, and list_homeric_places.

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 usage context: 'Use this to see which voyages the atlas reconstructs before fetching one.' It implies contrast with a singular fetch tool, though it does not formally name an alternative or state explicit when-not-to-use conditions.

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?

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: it lists all units, includes Evidence-First provenance, and frames the operation as a domain browse. No contradiction with 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?

Two dense sentences with no filler. The first sentence states purpose and output shape; the second provides usage routing. Every word 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, zero-required-parameter read-only listing tool with an output schema and rich annotations, the description is complete. It tells the agent what it returns, when to use it, and when to use the search alternative.

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 sole parameter (locale) is fully documented in the schema, including allowed values and default, so the description need not repeat it. The description adds no parameter-specific semantics, but 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 uses a specific verb ('List') and resource ('knowledge units'), defines the domain scope ('agentic & enterprise AI'), and enumerates the returned fields. It clearly differs from search and other list_* siblings by naming the exact resource.

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 this tool ('Use this to browse the domain') and names the alternative for question-driven lookups ('use `search` when you have a question rather than a slug'). This is clear 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?

Annotations already declare the tool read-only, idempotent, and non-destructive, so the bar is lower. The description adds meaningful behavior: the listing is exhaustive ('every SANTISMM Lab'), includes formulas/assumptions/citation URLs, and the optional kind restriction changes the result scope. Nothing contradicts the openWorldHint or other 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?

Two sentences with zero filler. The core action and return contents are front-loaded, followed by usage and filtering guidance. 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?

Low complexity (one optional enum parameter), an output schema, and safety annotations mean the description need not explain return format or side effects. It covers what is listed, the discovery purpose, and when to filter — enough for an agent to invoke it correctly. The only omission, an explicit pointer to get_lab for single-Lab detail, is minor at this complexity.

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 description already explains 'Restrict results to one Lab kind. Omit to list every Lab.' The description adds value by mapping the parameter to user phrasing ('when the user specifically asks for a calculator, converter, experiment or educational game'), helping the agent decide when to pass kind. This justifies a step above the baseline.

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') and a precise resource ('every SANTISMM Lab'), and enumerates what each listing contains (inputs, outputs, assumptions, formulas, citation URL). The resource-specific naming and the title's four Lab kinds distinguish it clearly from sibling list_* tools and from get_lab.

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 use case: 'Use this to discover interactive and machine-readable tools.' It also instructs when to apply the filter — 'filter by kind when the user specifically asks for a calculator, converter, experiment or educational game.' It stops short of naming alternatives or exclusions (e.g., when to prefer get_lab for a single Lab), so it falls just below fully explicit routing.

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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations by stating that it returns the complete set of patterns with slug, category, name, summary, and provenance, reinforcing the openWorldHint=false semantics.

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 two sentences with no wasted words. The core purpose and output fields are front-loaded, and the usage guidance is delivered efficiently in the second sentence.

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-only list tool with one optional parameter, rich annotations, and an output schema, the description covers all essential decision points: what is returned, the scope, and when to choose an alternative. 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 description coverage is 100%, and the only parameter, `locale`, is fully documented in the schema with an enum and description. The tool description adds no extra parameter guidance, which is acceptable given the schema's completeness.

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 ('List all Enterprise AI patterns'), identifies the item type ('reusable agentic design patterns'), and names the exact fields returned. It also differentiates itself from the sibling `search` tool, so an agent can tell them apart 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 when to use this tool ('browse the catalogue') and when to use the alternative (`search` when looking for a pattern that solves a problem). This gives clear routing guidance with no inference required.

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?

Even with annotations already indicating read-only, idempotent, and non-destructive behavior, the description adds valuable behavioral detail: ranked results, accent-insensitive matching, multi-language support, and per-hit relevance scores plus matched fields. This goes well beyond the structured annotations and provides actionable expectations.

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 sentences, each earning its place: scope, language/accent behavior, result details with follow-up instruction, and usage routing. The tool's purpose is front-loaded and there is no filler or repetition of schema 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?

The annotations cover safety semantics, the schema covers all parameters, and an output schema exists. The description supplies the remaining operational context: when to invoke it, what results look like, and how to retrieve full details. Nothing critical is missing for an agent to call it effectively.

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 baseline is 3. The description adds meaningful query-construction guidance beyond the schema by saying to query in the user's own words and noting that accents are ignored. It does not elaborate on limit, locale, or domains, 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?

The description clearly states a specific verb and resource: 'ranked keyword search across the whole corpus' with domain examples. It is unambiguous about what the tool does, but it does not explicitly differentiate itself from the sibling tools 'search_all' and 'search_articles', so it stops short of 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?

The description gives strong when-to-use guidance: 'Use this before any `get_*` tool whenever you have a question rather than an identifier.' It also tells the agent to follow up with the matching get_* tool. However, it does not mention when not to use this tool or point to alternatives like search_all or search_articles.

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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: it searches multiple surfaces in one call, routes calculator-shaped questions toward Labs, and tells the agent that results will name the next tool to call.

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 dense sentences, each earning its place: the first defines scope, the second gives explicit usage timing, and the third explains result routing. No filler or repetition of schema details.

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-surface search tool with four parameters, an output schema, and rich annotations, the description covers scope, usage timing, and post-invocation routing. It could be slightly more explicit about which simpler sibling to use for plain core-knowledge queries, but that gap is minor given the 'rather than only a core knowledge unit' phrasing.

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 is already documented in the schema. The description adds only general context about surfaces and Labs routing, not parameter-level syntax or constraints, so 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 names a specific verb ('Search') and a precise resource set — core corpus, first-party essays, executable Labs, epistemic claims, and the Homeric Atlas — and positions it as an all-surfaces entry point. It also distinguishes it from narrower single-surface tools by noting it is for questions that may need calculation, essay, or claim-audit results.

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 conditions for when to use this tool first: questions that may require calculation, a long-form essay, or a claim audit rather than only a core knowledge unit. It does not explicitly name sibling alternatives for the non-target cases, so it stops short of full when-not/alternative 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral details beyond annotations: ranking, accent-insensitive matching, and the exact fields and scope searched. It does not disclose rate limits or pagination nuances, but the output schema and annotations lower that burden.

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 with no wasted words. The first sentence front-loads what the tool searches and the key behavioral modifiers, and the second sentence gives immediate usage direction and a follow-up pointer.

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 full schema documentation, rich annotations, and an output schema, the description covers the essential context: what is searched, how results behave, when to use it, and what to do next. No critical operational information 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 description coverage is 100%, so the input schema already documents all three parameters, including the locale enum and default limit. The description mentions searched fields but adds no additional parameter semantics beyond what the schema provides, so the baseline score 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 states a specific verb and resource: ranked, accent-insensitive full-text search over every first-party essay. It also enumerates the indexed fields (titles, summaries, topics, bodies), making the tool's scope and behavior distinct from generic search or list tools.

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 when to use this tool: when long-form analysis about a topic is needed. It also provides a clear follow-up step, `get_article`, for retrieving the complete essay. However, it does not explicitly contrast this with sibling alternatives like `search_all` or `list_articles`, so it stops short of full 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.