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 declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds genuinely non-derivable behavior: no new aggregate score is computed, and benchmarks with comparable_across_labs=false reflect a single lab and should not drive a decision. That data-quality caveat is the kind of context annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then usage routing, then the data-quality caveat, in three tight sentences with no filler. Slightly dense with parenthetical field lists, but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need no explanation. Scope, the 'no aggregate computed' limit, the routing condition, and the comparable_across_labs caveat together give an agent everything needed to call and interpret this correctly; openness is covered by openWorldHint.

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 both parameters are documented there, so the baseline is 3. The description does clarify the intent of the optional profession parameter (include the models' rows in its ranking) and implies the minItems=2 constraint, but adds no syntax, format, or resolution guidance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('put two or more frontier models side by side on the benchmark results') and enumerates what is surfaced per benchmark (score, unit, source table, evidence grade). It also names the sibling it is not (recommend_model_for_profession), so an agent can distinguish it without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit trigger ('use this when the user is choosing between specific models') and an explicit exclusion with the alternative tool named for the opposite case (user has not named any models). Nothing about routing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context by disclosing what the returned body contains, including that it composes patterns/knowledge — implying relational expansion beyond a flat record.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the core action and the usage trigger front-loaded in that order. Every clause earns its place by either defining scope or routing the agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the description still summarizes the payload shape. With only two parameters (one required), the description plus schema gives an agent everything needed to call 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 coverage is 100%: slug has an example value and locale documents its enum options and default. The description only adds the provenance of the slug (from search/list_architectures), which is marginal beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get one reference architecture by slug') and enumerates the payload contents (request flow, reference scenario, KPIs, cost & scaling, composed patterns/knowledge). 'One ... by slug' cleanly distinguishes it from the plural sibling list_architectures.

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 the prerequisite workflow: 'Use this once `search` or `list_architectures` has given you a slug.' It names both alternative routes for obtaining the identifier, leaving no inference needed about when to reach for this tool.

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

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

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 declare readOnly/idempotent/non-destructive, so the safety bar is low; the description clears it by disclosing staleness semantics — a `last_verified` far in the past means the copy is a snapshot, and the agent should consult the hosted endpoint before repeating the current role. That is actionable behavioral context beyond 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 front-loaded sentences: what is returned, when to use it, and the staleness caveat. The payload enumeration is long but each item aids selection, and the operational warning is placed last where it belongs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return-format detail is not required, yet the description still lists the facts for selection purposes. Zero params plus full annotation coverage means the only real gap would be staleness, which is explicitly addressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies; no parameter-level detail is needed or missing.

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?

Specific verb+resource ('Get the author's professional profile as structured facts') with an enumerated payload — name variants, current role, previous organisations, authored frameworks, citation, licence, verification date. No sibling tool covers attribution, so it is trivially distinguishable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit trigger: 'Use this to attribute or cite anything this server returns.' That is a clear context for invocation. It stops short of naming when not to use it or pointing at an alternative, but no sibling overlaps this function.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the breadth of the returned record and a citation convention ('Cite `canonical_url` with `dataset_version`'), which is not derivable from any structured field. It does not mention behavior on an unknown slug.

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, no preamble: the returned content is front-loaded and the workflow/citation guidance follows. The middle enumeration is long but each item is a distinct field an agent would otherwise have to discover, so it earns its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation—the description's field list is over-delivery rather than a necessity. Combined with the routing guidance and citation convention, an agent has enough to select and call this correctly; only failure behavior on a bad slug is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single parameter is already documented with examples ('swe-bench-pro') and the slug-or-name rule. The description's 'by slug or name' only restates the schema, so the baseline 3 applies with no added 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?

States a specific verb and resource ('Get one benchmark by slug or name') and then enumerates exactly what comes back: what it measures, SOTA, saturation, headroom, human baseline, source/notes, radar axis, model scores, profession rankings. This is clearly distinguishable from the sibling list_benchmarks, which only enumerates.

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 situates the tool in a workflow: 'Use this after `list_benchmarks` or `search_all`, or to check what a ranking rests on.' It names the alternatives that produce the required slug, but does not state a when-not condition (e.g., that bulk enumeration belongs to list_benchmarks).

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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and repeat-call profile is fully covered without the description. The description adds a preview of the returned content, but since a structured output schema exists this is largely redundant; it says nothing about error behavior for unknown slugs or any auth/rate considerations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler. The purpose and payload preview come first, then the prerequisite, so the most decision-relevant information 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 single-resource fetch with strong annotations, a 100%-covered schema, and an existing output schema, the description supplies everything an agent needs: what it fetches, what it returns, and when to reach for it. No material gap remains.

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 both parameters (slug, locale enum) are documented in the schema with an example and default. The description only restates 'by slug' and omits the locale parameter entirely, so it adds no meaning beyond the schema — the baseline 3 for fully covered params is correct.

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 AI governance unit by slug') and even previews the payload's content (scope, requirements, controls, checklist, pitfalls). This clearly separates it from list_governance (plural, listing) and search, so an agent can pick it without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly sequences the workflow: 'Use this once search or list_governance has given you a slug.' This names the alternative tools and the condition under which this one is the right call, leaving nothing to inference.

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

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

Annotations already cover readOnly, idempotent, non-destructive, closed-world semantics, so the bar is lower. The description adds useful content-level context — the full Markdown body, provenance, and related ids are returned — which goes beyond the structured fields. It does not describe behavior for an unknown/missing id, a minor 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 tight sentences, front-loaded with what the tool returns, followed by the routing condition. No filler and nothing repeated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't detail return values, and annotations plus full schema coverage carry the rest. It is essentially complete for a simple single-fetch tool; only the missing-id/error case is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (id, locale) are already fully documented, including the enum. The description's id/slug mention adds marginal value but mostly restates 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?

States a specific verb (get) and resource (one Harness Engineering Handbook chapter), gives the id format example ('HRN-001') and slug alternative, and names itself as distinct from the list/search siblings. An agent can tell it apart from list_handbook or search without opening a 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?

Explicitly routes the agent: 'Use this once search or list_handbook has given you an id.' It names both alternative tools and the precise condition that selects this one, leaving little to inference.

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

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

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that the response shape changes with locale (full entry vs single-locale body), which is useful, but it does not cover failure behavior for a missing slug or any limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with what the tool returns before the routing advice. No filler and no restatement of the title.

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?

Purpose, the when-to-use trigger, and the locale-conditional return are all present, and an output schema plus rich annotations cover the rest. The only real gap is that error behavior for an unknown slug is unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description goes slightly beyond it by explaining the observable consequence of `locale` — you get only a single-locale body instead of the full entry. It does not add anything on `slug` beyond the schema's example.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get one knowledge unit by slug') and names the identifier used for lookup, so it is distinguishable from the list_/search_ siblings. It does not explicitly differentiate itself from other singular getters like get_article or get_pattern, which keeps it 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?

Gives an explicit usage condition: 'Use this once search or list_knowledge has given you a slug,' naming the upstream alternatives. There is no when-not guidance (e.g. what to do if you have no slug), but the required context is clear.

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

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

With 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuine value by enumerating what the overview contains — tools, identifiers, citation rules, languages, licence, bulk-ingest URLs — though it says nothing about auth needs or freshness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight clauses with the entry-point directive front-loaded and the payload contents following. No filler or restated name/title boilerplate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-format explanation is not required. The description covers purpose, scope and the kind of content returned, which is sufficient for a no-parameter navigational tool; only minor use details (e.g. how to consume the emitted identifiers) are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify about 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?

States a concrete verb and resource ('Get the complete MCP map') and scopes the return to the five-domain core plus named extra surfaces. The 'start here' framing implicitly separates it from the numerous get_/list_/search_ siblings, but no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Start here' gives a clear calling context: use this before drilling into the specific retrieval tools. It does not spell out when NOT to use it or name a concrete alternative, but the entry-point role is unambiguous.

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

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

Annotations already declare a safe, read-only, idempotent operation, so the safety profile is covered. The description adds content context (problem, solution, KPIs, failure modes, lessons), but does not discuss error behavior, locale effects, or other traits beyond 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 short sentences, front-loaded with the core action and then the usage condition. Every sentence earns its place with no padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, the annotations fully cover safety, the schema fully documents both parameters, and an output schema exists. The description provides sufficient context for an agent to know what it returns and when to call it.

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?

With 100% schema description coverage, the schema already documents both `slug` and `locale` including examples, length bounds, enum values, and default. The description adds only the phrase 'by slug', so it does not meaningfully extend parameter meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: retrieve one Enterprise AI pattern by slug. It also lists the pattern sections returned, making the resource concrete and distinguishable from sibling list/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?

Explicitly says to use this after `search` or `list_patterns` has produced a slug. This names the likely alternatives and the triggering condition, leaving little inference needed.

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, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral detail the annotations cannot convey: traversal is bidirectional (outgoing links and incoming references) and each neighbour carries a relationship type. It omits edge cases such as isolated units or result limits, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, and the core semantics (what neighbours means, both directions) are front-loaded before the usage hint. 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?

An output schema exists, so return-value detail is not required, and the description still summarizes the shape (neighbours with relationship types). It is essentially complete for a 3-parameter read tool; only minor edge-case behavior (empty results, traversal depth) is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and all three parameters (slug, domain, locale) are fully documented in the schema, including enum values and the handbook/HRN special case. The description only says 'given a unit' and adds no parameter meaning beyond that, 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?

The description gives a specific verb (traverse/return neighbours) on a specific resource (the knowledge graph), and defines the output precisely as outgoing links plus incoming references with relationship types. It is clearly distinguishable from the get_* siblings, which fetch a single unit rather than its graph neighbourhood.

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 reach for it: 'Use this after a `get_*` call to widen an answer with adjacent units.' That is a clear usage context tied to a named sibling family. There is no explicit when-not or boundary case (e.g. no-neighbour units), 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 declare readOnly, idempotent, non-destructive and openWorld=false, so the safety profile is covered by structured data. The description adds the returned field set and browsing semantics, but says nothing about pagination, result size, or ordering for a 'list all' operation. Adding some value over annotations, but not rich behavioral context.

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, no waste. The resource description and returned fields come first, and the routing guidance to `search` follows immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, annotations covering the safety/idempotency profile, and a fully documented single optional parameter, the description only needs to state what it lists and when to prefer it, which it does.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one optional parameter (locale) and schema description coverage is 100%, including the enum values and the 'Default: en' note. The description adds no parameter-level information, which is acceptable given the schema fully documents it.

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 resource (reference architectures), and defines the term inline as 'end-to-end enterprise agentic blueprints' so the agent knows exactly what domain object is returned. It also enumerates the returned fields, making the scope unambiguous against retrieval siblings like get_architecture.

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 instruction: browse with this tool, or use `search` when starting from a use case rather than a name. This is a clear when-to-use and when-to-use-something-else statement naming the alternative sibling.

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 this as a safe, idempotent, read-only, open-world read, so the description does not need to restate safety. It does add behavioral value the annotations cannot: the tool spans two distinct datasets (agentic catalogue vs. complementary list) and reports SOTA/saturation/headroom fields, which tells the agent what the results contain. No disclosure gap of consequence.

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, front-loading the scope ('List every benchmark...') and ending on the actionable next step. 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?

A single optional enum parameter, an output schema (so return values need not be described), and full annotation coverage. The description supplies scope, content, and the follow-up call — nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the enum values/omission behavior are documented in the schema, setting a baseline of 3. The description goes slightly beyond by mapping each enum option to substantive content ('agentic benchmarks' vs. 'vision, long context, factuality, instruction following, language'), which helps the agent decide whether to pass a `list` value at all.

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?

Uses a specific verb ('List every benchmark') plus the exact resource (the AI Agent Benchmarks catalogue and its complementary list), and enumerates the content dimensions covered (SOTA, saturation, headroom vs. vision, long context, factuality). It also names the downstream sibling get_benchmark, so an agent can separate this from the many other `list_*`/`get_*` pairs.

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 the workflow: use this tool to find a benchmark slug, then call `get_benchmark`. That names the alternative and the condition that selects it, which is exactly what a discovery tool needs. No misleading or missing 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 readOnly, idempotent, closed-world behavior, so safety semantics are covered. The description adds that this returns a list with specific fields and that a locale affects the returned body, which is useful context beyond the annotations, though it doesn't discuss ordering or pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loading the resource and scope followed by routing guidance. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list operation with full annotations, an output schema, and a fully documented parameter, nothing needed for correct invocation is missing. The description covers scope, fields, and alternative routing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one optional parameter, locale, and its schema already documents the enum and default with 100% coverage. The description adds no parameter details, 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?

The description uses the specific verb 'list' with the resource 'AI governance units', enumerates the concrete categories and standards covered (EU AI Act, ISO 42001, NIST AI RMF), and states the returned fields. It is clearly distinguishable from siblings like get_governance and search.

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 ('browse the regulations and standards') and names the alternative with its corresponding use case ('use search for an obligation or control'). This is a textbook when-to-use-vs-alternative statement.

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/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds useful scope context (what the corpus covers) but says nothing about pagination, ordering, or result sizing. With annotations carrying the behavioral burden, this is an adequate but not rich disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first clause, followed by coverage enumeration and the usage rule. The long topic list is informative for discovery but slightly padded; still two sentences with no wasted framing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists (so return shape needn't be described) and annotations cover the safety profile. Purpose, coverage scope, and the alternative tool are all present — nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (locale) and the schema documents it at 100% coverage with an enum. The description adds no locale guidance, so the baseline 3 applies — the schema does all the work here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the Harness Engineering Handbook chapters'), gives the ID prefix (HRN-001…) and enumerates the corpus scope, so an agent knows exactly what this returns. It is clearly distinguished from sibling get_handbook and from search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'Use this to see the chapter map; use `search` when you have a topic rather than a chapter.' Both the when and the when-not (with a named alternative) are stated.

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

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

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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the field list of what comes back, but says nothing about result volume, pagination, or ordering for an unbounded 'list all' operation. Adequate given the annotation coverage, 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, front-loaded with the action and scope, with the routing hint second — no wasted preamble. The final clause is mildly muddled rather than bloated, keeping it just short of ideal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a full output schema and rich annotations, the description need not explain return values or safety, and it correctly focuses on purpose and sibling routing. It is nearly complete; the only gap is whether the 'all' listing is paginated or bounded, which an agent invoking it might want to know.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single optional `locale` parameter with 100% schema description coverage and a documented enum plus default, so the schema already carries the semantics. The description adds no parameter-level detail (e.g., whether locale affects only the body or also titles), so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('List') and resource ('knowledge units'), defines the domain ('concepts on agentic & enterprise AI'), and enumerates the returned fields. It explicitly distinguishes itself from the sibling `search`, so an agent can tell the two apart without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names the alternative (`search`) and the condition that selects it ('when you have a question'), which is clear routing guidance. The trailing qualifier 'rather than a slug' is slightly confusing, since listing takes no slug parameter and slug-based retrieval is what `get_knowledge` does, leaving a small ambiguity about the browse-vs-fetch boundary.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds the returned field list and browsing purpose, but does not disclose additional behavior such as pagination, ordering, or locale effects on the returned body beyond what structured fields already cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the first front-loads the action, resource, and returned fields; the second routes the agent to the correct alternative. 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?

For a low-complexity list tool with one fully documented optional parameter, annotations, and an output schema, the description is largely complete. It could mention `get_pattern` for retrieving a single pattern's full details, but the essential browse-vs-search decision is covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one optional enum parameter, locale, and schema description coverage is 100%. The schema already documents the language values and default; the description adds no locale-specific semantics beyond that. Baseline 3 is appropriate when the schema carries parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List all Enterprise AI patterns'), enumerates returned fields, and explicitly distinguishes the browse use case from the search use case. An agent can tell it apart from search and get_pattern 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?

Explicitly says to use this tool to browse the catalogue and to use `search` when looking for a pattern that solves a problem. The alternative selection condition is stated directly.

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, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description's extra detail (direct/indirect marking, top-ranked model) is return-content information that the output schema already carries, so it adds little behavioral context 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?

The purpose is front-loaded in the first sentence and the routing instruction follows immediately. The opening sentence is dense with stacked clauses, but every clause carries distinguishing information, so it stays close to earning 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?

With an output schema present, the description need not explain return fields, and annotations cover safety. It supplies purpose, filtering intent and the follow-up tool, so an agent has everything needed to call it and chain 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 group, locale (including the English-fallback caveat) and evaluation are all documented in the schema itself. The description alludes to the direct/indirect distinction but adds no syntax or semantics beyond what the schema already provides, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (list professions) and pins down the payload precisely: professions with an AI-model ranking from independent benchmarks, marked direct/indirect, with today's top model. The parenthetical examples and the 'direct or indirect evaluation' detail make it unmistakably distinct from 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?

Gives an explicit purpose statement and next step: 'Use this to find the profession id; then call `recommend_model_for_profession`.' This names the downstream tool and the condition that selects it, leaving no ambiguity about when to reach for this versus the recommendation 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 cover the safety profile (readOnly, idempotent, openWorld), yet the description adds substantial behavioral context: the conditional 'indirect' handling and the instruction to present results as a guide rather than a measurement, plus the citation requirement pairing canonical_url with dataset_version. This is exactly the value-beyond-annotations the bar asks for.

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 first sentence is a dense list of return artifacts, but the usage and conditional-rendering sentences are tightly scoped and front-loaded. Slightly overstuffed, yet nearly every clause carries actionable 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?

With an output schema present the description need not explain return values, yet it still supplies the usage prerequisite, the indirect-type caveat, and the citation contract. For a read-only ranking tool, an agent has everything needed to call and present results 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 id, limit and locale are already fully documented in the schema; the description adds no parameter-level syntax or format detail. Baseline 3 is appropriate when the schema does all the work.

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: produce a model ranking for one profession, enumerating the exact artifacts returned (best result, runner-up, best value, best open-weights, full table). This clearly distinguishes it from siblings like compare_models or list_professions, which do different things.

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 names the triggering situation ("someone asks which AI model to use for their job") and the prerequisite ("after list_professions or search_all has given the id"). It also gives a conditional handling rule for evaluation.type == 'indirect', which is genuine 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 establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description still adds real context beyond them: cross-language matching, accent-insensitivity, that each hit carries a relevance score and matched fields, and the recommended follow-up with get_*. It stops short of stating result caps or ranking model details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the core scope, then behavior, then the routing instruction. Every sentence carries distinct information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be described, and the description still usefully previews the hit shape and the follow-up path. It is nearly complete for a search tool; the missing piece is any differentiation from the sibling search family, which the agent needs to disambiguate.

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 query, limit, locale and domains with defaults and bounds. The description adds only generic guidance ('query in the user's own words', 'matches every language') rather than new syntax or format detail, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Ranked keyword search across the whole corpus') and enumerates the covered domains, so the agent knows exactly what is searched. However, it does not distinguish itself from the sibling 'search_all', which the phrase 'across the whole corpus' makes it sound identical to, leaving real ambiguity about which search entry point to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'Use this before any get_* tool whenever you have a question rather than an identifier.' That is a clear when-to-use vs when-not rule against the get_* family. It gives no guidance against the other search siblings (search_all, search_articles), which is the more likely confusion.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: results carry a suggested next tool, and query shapes are routed toward Labs or benchmarks. It does not, however, disclose latency, result-size or pagination behavior.

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, front-loaded with the scope before the usage guidance and the routing note. The surface enumeration is dense but each item earns its place by telling the agent what is reachable in one call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value shape need not be restated, yet the description still contributes the key post-call behavior (results name the next tool). For a broad federated search, everything an agent needs to decide to call it and what to do after is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters — including the tricky distinction between `locale` and `content_locales` — are already documented in the schema. The description adds no parameter-level detail, 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 (Search) and enumerates exactly what resources are covered — core corpus, essays, Labs, claims, Homeric Atlas, benchmarks — in one call. This clearly separates it from siblings like `search` and `search_articles`, which cover narrower scopes.

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 says 'Use this first when a natural-language question might require a calculation, a long-form essay, a claim audit or a model choice' and then names the routing destinations for two classes of query. It gives both the when-to-use condition and the when-to-defer 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, 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.