principia

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

Annotations already establish the tool as read-only and non-destructive, so the description's job is lighter. It adds useful behavioral context by explaining that each row aggregates a normalized item stem across multiple source instruments via source_items[], which goes beyond what the schema or annotations reveal.

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 deliver the core action, the domain context, and the aggregation model with no filler. The primary purpose 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?

For a simple paginated list tool, the description covers the essential purpose and row semantics, and an output schema exists. However, it omits routing guidance against sibling tools and leaves pagination parameter behavior undocumented, creating a noticeable but not severe completeness gap.

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

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

The only parameters are limit and offset, and schema description coverage is 0%, so the description carries the burden of explaining them. It does not mention pagination, ordering, or default behavior. The parameter names are conventional enough to be partially inferable, but the description adds no parameter-level 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?

The description uses a specific verb ('List') with a clear resource ('CanonicalSurveyItem rows') and adds a distinguishing qualifier ('PRN-050 item-level dedup spine'). It also explains the core aggregation behavior ('normalized item stem across N source instruments'), making the tool's role clear relative to sibling lookup/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?

No explicit guidance is given about when to use this list tool versus the sibling canonical_items.lookup or canonical_items.search tools. The listing intent is implied, but there are no conditions, exclusions, or alternatives named to help an agent choose correctly.

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?

Discloses that unknown IDs return found:false, which is useful non-obvious behavior not captured by the readOnly/openWorld/destructive annotations. This adds real behavioral context beyond the structured hints.

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 delivers the verb, resource, parameter, and example; the second covers the not-found behavior. 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 one-parameter lookup tool with an output schema, the description covers the lookup key, example format, and an important edge-case behavior. Nothing essential is missing for correct invocation.

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

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

The input schema only says id is a non-empty string, but the description identifies it as canonical_item_id and gives a realistic example format. This fully compensates for the 0% schema description 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?

States the exact operation: 'Lookup one CanonicalSurveyItem by canonical_item_id' and includes a concrete example ID. This clearly distinguishes it from list/search siblings, which work over collections rather than a single keyed lookup.

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

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

Provides clear context that this tool is for retrieving one item by exact ID. It does not explicitly say 'use search when the ID is unknown,' but the single-ID lookup instruction makes the appropriate use case evident.

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 mark the operation as read-only and non-destructive. The description adds behavioral detail beyond annotations: it specifies which fields are searched and explains how instrument_id filters by source_items[] references. There is 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 tightly written sentences. The action is front-loaded and the optional filter is appended without redundant phrasing or filler.

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

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

For a search tool with one required parameter, one optional filter, and one optional limit, the description covers the main behavior and filter semantics. Required/optional status is evident from the schema, and the output schema handles return values. No critical 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 0%, so the description carries the burden. It gives semantics for q (keyword search) and instrument_id (filter by referenced instrument), but limit is not explained in the description. The schema does constrain limit's numeric range, so this is a minor gap.

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 it performs keyword search over normalized_text and alternative_texts for canonical items, with an optional instrument_id filter. The verb and resource are explicit, and 'canonical items' differentiates it from sibling search tools on other resource types.

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

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

No guidance is given on when to choose this tool over siblings such as canonical_items.list/lookup or items.search. The description states what it does but not when to use it vs 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=true and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: the tool returns empty until the synthesis engine ships, and warns that the prior's r aggregates pooled/corrected effects rather than raw r — genuine operational context. The caveat is dense and internally referenced, which keeps it from 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?

The first sentence is front-loaded and precise, and the second is a useful state caveat. The third sentence is a jargon-heavy run-on packed with internal codes (PRN-N1013-M4, EFFECT_ESTIMATE_GLOSSARY.units_not_recorded, @people-analyst/measurement-core) that an agent cannot readily parse, diluting the otherwise tight structure.

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 values need no explanation, and annotations carry the safety profile. However, for a 5-parameter tool at 0% schema coverage, the description leaves sample_culture completely undocumented and gives no parameter types or formats, so it is only partially complete.

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

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

Schema description coverage is 0% for 5 parameters, so the description must compensate and only partly does. It names id, from_construct_id, predicate, and to_construct_id and clarifies the OR relationship between the id path and the triple path, but sample_culture is never mentioned in either schema or description.

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 (Lookup) and resource (synthesized Bayesian prior) and enumerates the two lookup keys: id or the (from_construct_id, predicate, to_construct_id) triple. It distinguishes itself from the sibling canonical_priors.search by naming the exact identifiers it accepts, though it never explicitly contrasts the two.

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 explains how to invoke it (by id OR by triple) but gives no explicit when-to-use guidance against canonical_priors.search or the other *.lookup siblings. The 'Empty until PRN-021 synthesis engine ships' clause is a meaningful availability caveat, but it is framed as a state note rather than 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?

The description usefully discloses that the tool currently returns nothing until the PRN-021 synthesis engine ships, which is important behavioral context beyond the readOnlyHint annotation. It does not contradict annotations and adds real operational knowledge.

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: the first front-loads the action and primary filters; the second adds a critical availability caveat. No wasted words, and the structure is easy for an agent to parse.

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 empty-until-PRN-021 warning is valuable and makes the current state clear. However, with 8 optional parameters and no schema descriptions, an agent lacks enough detail to construct meaningful queries once the engine ships, especially for freshness and informativeness filters.

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 0%, so the description should compensate for the 8 parameters. It only names from, predicate, and to, leaving limit, construct IDs, min_freshness_score, and min_informativeness unexplained. This is a meaningful gap.

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 ('Search') and resource ('canonical priors') and names the key triple dimensions from/predicate/to. It does not explicitly differentiate from the sibling canonical_priors.lookup, but the search scope is clear enough.

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

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

The description gives no guidance on when to use this tool versus canonical_priors.lookup or the many other search siblings. The statement about being empty until PRN-021 is a status warning, not usage guidance; no exclusions or alternatives are mentioned.

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, covering the safety profile. The description adds modest behavioral context by mentioning that both id-keyed and doi-keyed candidates are scanned and that exactly one citation is returned, but it does not disclose behavior when both id and doi are supplied or when no match is found.

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

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

The description is a single tight sentence that front-loads the core purpose ('Lookup one citation by id OR doi') and then adds a brief implementation note. There is no filler or redundant information.

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

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

For a simple read-only lookup with an output schema present, the description covers the main parameters and the tool's scope. The only notable gap is the lack of explicit guidance on parameter combination and requiredness, but this does not make the tool unusable.

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 0%, so the description must compensate. It does add meaning by identifying id and doi as alternative lookup keys, but it does not specify whether at least one is required, what formats are expected, or what happens if both are provided. This leaves meaningful gaps for a two-parameter tool.

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 ('Lookup'), a precise resource ('one citation'), and the exact lookup keys ('by id OR doi'). It clearly distinguishes this tool from the sibling citations.search tool by emphasizing exact identifier lookup rather than free-form 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?

The description clearly implies the tool should be used when the agent has an exact citation id or DOI. It does not explicitly mention alternatives or exclusion conditions, but the lookup/search distinction across sibling tools makes the intended context reasonably 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description usefully adds the searchable fields, but it does not disclose match semantics, case sensitivity, pagination behavior, or default limit handling. 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?

The description is a single sentence with no filler: the verb, resource, and searchable fields are all front-loaded. Every word contributes meaning, and the definition is easy to scan quickly.

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

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

For a simple read-only search tool with an output schema, two parameters, and clear annotations, the definition is nearly complete. Minor gaps around query syntax and limit defaulting prevent a perfect score, but an agent has enough 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?

Since schema description coverage is 0%, the description must carry more weight. It establishes q as a keyword applied to citation fields, and limit is reasonably inferable as a result cap given the schema's maximum of 100. However, it does not explain query syntax, default limit, or whether all fields are searched in combination.

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 ('Keyword search') and a concrete resource ('citations') while listing exactly which fields are searched: title, apa_reference, doi, and authors. This clearly distinguishes it from sibling lookup and other domain-specific 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?

The description clearly frames the tool as a keyword-search operation over citation metadata, giving an agent an unambiguous cue for when to use it. It does not explicitly compare against citations.lookup or other alternatives, but the search/lookup distinction and field scope make the intended use 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by noting the tool returns resolved CanonicalVariable rows and supports filtering, but it does not disclose behaviors like default limits, ordering, or empty-result behavior. This adds some value without being fully transparent.

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

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

The description is short and front-loaded, with the main action and resource stated first. The reference 'PRN-271' is likely noise for an agent and does not clarify behavior, but the overall structure is efficient and easy to parse.

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 has an output schema and safe annotations, the description does not need to explain return values. However, it omits guidance on when to use list versus search or lookup, and it leaves parameter semantics largely unexplained. The description is minimally viable but has clear 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?

Schema description coverage is 0%, so the description must compensate for the absence of parameter documentation. It merely names the supported parameters (limit, offset, engagement_family_only, abstraction_level) without explaining their semantics, defaults, or interactions. The parameter names and enum values provide partial meaning, but the description adds little beyond restating the schema.

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

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

The description uses a specific verb and resource ('List canonical constructs') and adds a clarifying parenthetical ('resolved CanonicalVariable rows') that explains what kind of records are returned. It does not explicitly differentiate from sibling tools like search or lookup, but the list verb and resource identification make the core purpose clear.

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

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

The description gives no guidance on when to use this tool versus alternatives such as principia.constructs.search or principia.constructs.lookup. It implies a paginated listing use case but does not state when listing is preferred over searching or looking up individual constructs.

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 the safety profile is covered. The description adds valuable behavioral context beyond annotations: 'Unknown ids return found:false (soft validation)', informing the agent that invalid ids do not cause errors but return a soft failure marker.

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 core purpose is front-loaded, and the behavioral note about unknown ids is appended without redundancy. Every word earns its place.

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

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

For a simple one-parameter lookup tool with an output schema present and annotations covering safety, the description is largely sufficient. It explains what the tool does, the id format, and a key edge-case behavior. It does not elaborate on the meaning of 'canonical construct', but that is domain knowledge likely available elsewhere.

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

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

Schema coverage is 0% and the only parameter is a bare string `id`. The description compensates by explaining the id semantics: 'a canonical variable_id, e.g. VAR_000376', giving a concrete format example. This adds meaning beyond the schema's minLength constraint.

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

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

The description clearly states the specific operation: 'Lookup one canonical construct by id'. It specifies the resource (construct), the method (lookup by id), and the singular scope ('one'), which distinguishes it from sibling list/search/resolve tools without ambiguity.

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

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

Usage is implied by the phrase 'by id' — the agent can infer this tool is for when a canonical variable_id is known, versus search when it isn't. However, no explicit when-to-use or when-not-to-use guidance is given, nor are alternative sibling tools named.

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 record readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only — no mutation (curator-policy D4)'. It also adds meaningful behavioral detail: the composite-score ranking formula and available filters. 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 no filler: purpose and ranking are front-loaded, filters are listed compactly, and the read-only note closes the description. Every clause adds useful information.

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

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

Given the presence of an output schema, not detailing return values is acceptable. The description covers purpose, ranking, filters, and safety. The only meaningful gap is the lack of explicit sibling-tool routing and the unexplained limit parameter, but these are minor relative to the schema and annotation richness.

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 0%, so the description needs to compensate. It names three optional filters (min_reliability, cross_cultural_only, length_lte) and implies construct_id via 'given construct', which adds some guidance. However, it does not explain the semantics, ranges, or units of those filters, and it omits the limit parameter entirely.

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 concrete operation ('Return instruments'), a specific scope ('that measure a given construct'), and a ranking scheme ('composite score'). This is clear and distinguishes the tool from generic list/lookup siblings, though it does not explicitly name a sibling alternative.

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 natural use case is implied: when you have a construct and want measurement instruments, optionally filtered. However, it does not explicitly say when to prefer this over instruments.search or constructs.search, nor does it state exclusions or alternatives. Usage guidance is mostly inferential.

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, and the description reinforces this with 'READ-ONLY — does not mutate.' It adds meaningful behavioral detail about the matching algorithm and thresholds, which is beyond what annotations provide. 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?

The description is two sentences with no filler, front-loading the action and object first, then safety and matcher details. Every sentence earns its place and the structural cues make the optional parameters and read-only nature immediately visible.

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

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

The description provides the essential operational context: what is being resolved, against what store, which parameters matter, and with what matching thresholds. Since an output schema exists, return-value details are not required. The only notable gap is explicit guidance on when to choose this over sibling tools, but the matcher semantics largely cover the intended use case.

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 0%, so the description must compensate. It lists all three parameters in a structured form ({name, definition?, variable_code?}) and explains their role in matching, including specific similarity thresholds. This provides clear semantic meaning beyond the bare schema field names and types.

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 ('Resolve'), a resource ('source-side construct'), and the target ('canonical store'), which is clear enough to convey the core operation. It does not explicitly differentiate itself from sibling lookup/search tools, but the mention of a fuzzy matcher with thresholds signals a distinct resolution behavior.

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

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

The description implies when to use the tool through the matching thresholds ('name@0.9 / code@0.85 / definition@0.6'), suggesting fuzzy resolution rather than exact lookup. However, it does not explicitly state when to prefer this over constructs.lookup, constructs.search, or other siblings, nor does it provide exclusion criteria.

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 the safety profile is known. The description adds the specific fields being searched, which is useful behavioral context. It does not describe result format or pagination, but output schema likely covers that. It does not contradict annotations, and adds meaningful detail about what content is searched.

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 fluff, front-loaded with the core purpose. The parameter clarification is placed second, which is efficient. Every word earns its place.

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

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

Given that annotations cover the read-only nature and an output schema exists, the description is fairly complete. It states what is searched and the required argument name. However, it omits any mention of the optional `limit` parameter, and does not hint at result ordering or pagination. For a simple search tool, this is mostly adequate but has minor 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?

Schema description coverage is 0%, so the description must compensate. It clarifies that the search term is passed via `q` and not `query`, which is critical for correct invocation. However, it does not mention the `limit` parameter at all, leaving that undocumented. The description adds value for `q` but is incomplete for `limit`.

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 ('search') and resource ('constructs'), and explicitly lists the fields searched (name, definition, alternative_names, variable_codes). It also clarifies the argument name (`q` not `query`), which distinguishes it from other search tools. This is precise and unambiguous.

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

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

The description implies this is for keyword search over constructs, but it does not explicitly state when to use this tool vs alternatives like lookup or list. It provides no exclusions or alternative recommendations. The clarification about `q` is helpful but doesn't guide usage selection. Thus, usage context is implied but not explicit.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses the exact response shape, including the unusual array-shaped format for parity with equivalences and the fact that matches can contain 0 or 1 element. This is genuinely useful behavioral context not available in the schema.

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

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

Two compact sentences with no filler. The primary action and key information are front-loaded, and the return-shape note earns its place because it explains a non-obvious response convention.

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 lookup with readOnly annotations and an output schema, the description is complete. It covers the lookup key, the response shape, and cardinality, leaving no critical ambiguity for an agent deciding how 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?

The input schema only shows a generic string parameter named 'id' with no description, so the description compensates by identifying it as a critique_id. This gives the agent the semantic meaning needed to invoke the tool correctly, though it does not specify additional details like format or where the id comes from.

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, 'Look up one MethodologyCritique by critique_id,' and clearly identifies the resource and the lookup key. It also distinguishes itself from search siblings by emphasizing that matches contain 0 or 1 element.

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 makes the intended use clear: call this when you have a specific critique_id and expect exactly one result. It does not explicitly name the alternative search tool or state when-not-to-use, but the exact-ID lookup intent 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 readOnlyHint and destructiveHint, so the safety profile is covered. The description adds value by disclosing the AND-combination semantics and the 'curator-policy D4' read-only context, which are not present in the schema or 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 compact sentences front-load the core operation and filter semantics. There is no wasted text; every clause adds useful information.

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

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

For a search tool with an output schema and safety annotations, the description covers the essential filter behavior, combination rules, and read-only nature. The only notable gap is the absence of any mention of the limit parameter or differentiation from similar lookup/search tools, but the definition remains largely adequate.

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 0%, so the description must compensate. It explains the four filter parameters and their combination logic, but does not address the limit parameter or the meaning/format of subject_id. Enums cover three parameters' values, but the description still leaves some parameter semantics implicit.

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 action (Search) and resource (MethodologyCritique rows), and enumerates the filter dimensions. It clearly identifies what the tool does, though it does not explicitly contrast with the sibling lookup 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 gives concrete usage rules: all filters AND together and any subset of the four is valid. However, it provides no explicit guidance on when to choose search over the sibling critiques.lookup or other search tools, leaving selection mostly implied.

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 this as a safe, closed-world read, so the description is free to add value elsewhere — and it does, disclosing an output convention: basis naming per EFFECT_ESTIMATE_GLOSSARY and the 'basis not recorded' fallback for rows lacking a typed estimates block. That is genuine context beyond the safety hints, though the second sentence is dense and jargon-laden.

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, purpose front-loaded before the output-convention detail, with no filler. The second sentence carries heavy domain jargon and reference codes, but it is not 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?

An output schema exists, so return values need not be re-explained, and the glossary note adds some coverage. However, a 6-parameter filter tool with 0% schema description coverage and no usage guidance leaves the agent unable to disambiguate the three unnamed parameters or decide when this search beats its siblings.

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

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

Schema coverage is 0% and there are six parameters, but the description names only three (from, to, statistic_type) and adds no syntax, format, or value semantics for them. The parameters limit, to_construct_id, and from_construct_id are undocumented in both the description and the schema, and the three named ones get no explanation beyond their identifiers.

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 resource (EffectSize rows) plus the primary filter axes (from/to/statistic_type), so the agent knows the domain. It stops short of distinguishing this from the many sibling *.search tools, but the 'EffectSize rows' resource is specific enough to be identifiable.

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

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

There is no explicit when-to-use guidance and no mention of alternatives among the large set of sibling search/lookup/list tools. The agent must infer that this is the right tool from the resource name alone.

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 mark readOnlyHint=true and destructiveHint=false, and the description adds valuable behavior beyond that: server-side pair ordering normalization and the array-shaped response pattern. It does not mention pagination or auth, but these are less critical for a read-only lookup.

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, information-dense sentences. The core operation and access modes are front-loaded, and no sentence repeats schema or annotation 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?

Covers lookup modes, tuple semantics, optional mapping_method, pair-order normalization, and return shape. The only notable gap is that the schema marks all parameters optional while the description implies at least an id or tuple should be supplied, but does not explicitly state that constraint.

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?

Despite 0% schema description coverage, the description compensates by explaining how id, construct_id, instrument_a, instrument_b, and mapping_method combine into meaningful lookup modes. It also clarifies that instrument_a/b order is irrelevant. The id parameter gets less explanation, but 'by id' is self-explanatory.

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 ('Look up') and a specific resource ('InstrumentEquivalence rows'), and enumerates the exact access paths: by id or by canonical tuple. This distinguishes it from sibling search tools, which imply broader or fuzzier result sets.

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 clearly indicates when to use this tool: when you have an id or the construct/pair/method tuple. It also notes the optional mapping_method. It does not explicitly state 'use search when you lack exact identifiers', but the lookup-vs-search distinction is strongly implied.

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 the safety profile is covered. The description adds valuable behavioral context beyond that: instrument_id matches either side of the equivalence pair, and mapping_method is an optional filter. This helps the agent understand matching semantics not visible from 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 concise sentences with no fluff. It front-loads the core search behavior, then adds the key matching nuance and the optional filter. 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 search tool with an output schema and read-only annotations, the description covers the main filters and the crucial 'either side' matching rule. The only notable gap is the absence of guidance on selecting this tool over its lookup sibling, but that is more of a usage-guidance issue, and the essential invocation details are 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 0%, so the description carries the burden of explaining parameters. It covers construct_id, instrument_id (including the 'either side' nuance), and mapping_method, but omits limit. Though limit is fairly self-explanatory from its name and schema constraints, the description does not fully compensate for the lack of schema descriptions.

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

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

The description clearly states that the tool searches InstrumentEquivalence rows using construct_id and/or instrument_id, naming the specific resource and the two main filtering criteria. It does not explicitly differentiate from the sibling principia.equivalences.lookup, but the action and resource are unambiguous.

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

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

No guidance is provided about when to prefer this tool over its siblings, particularly over principia.equivalences.lookup. The description does not state conditions, exclusions, or alternatives, leaving the agent to infer when this search tool is appropriate.

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 the safety profile is covered. The description adds the semantic filter ('claim subject') but does not disclose behavior such as default limits, handling of the subject_type filter, or edge ordering. 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?

The description is a single, front-loaded sentence with no filler or repetition. Every word contributes to the core behavior, and it is easy to parse quickly.

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 and annotations covering safety, the core return type and read-only nature do not need elaboration. Still, the description omits guidance on optional parameters (subject_type, limit) and does not contextualize itself against the many sibling evidence tools, leaving the agent under-equipped for nuanced selection.

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 0%, so the description needs to compensate for all three parameters. It clarifies only entity_id (as the claim subject) and says nothing about the meaning or effect of subject_type or limit. The parameter names and enum help, but the description leaves too much to inference.

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

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

The description states a clear verb ('return'), a specific resource ('Evidence[] edges'), and a precise filtering condition ('name a given entity_id as the claim subject'). It distinguishes this tool from siblings like principia.evidence.trace by emphasizing the subject-based edge query, though it does not explicitly name alternatives.

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

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

The description implies the tool should be used when an agent needs evidence edges where a specific entity is the claim subject. However, it provides no explicit guidance about when to prefer this over related tools such as principia.evidence.trace or principia.evidence_statements.search, nor any exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about data provenance ('owned, OA-sourced, attributed, stance-classified') and the display-oriented purpose, but it does not disclose limit behavior, pagination, or ordering. 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 first sentence front-loads the core search behavior and filters; the second adds the intended use context. Every phrase earns its place.

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

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

The description covers the main search modes and intended display context, and the output schema reduces the need to explain return values. However, it leaves min_grade and limit unexplained and does not clarify the expected format of from/to/construct values. It is sufficient for selection but not fully complete for 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 description coverage is 0%, so the description must compensate. It explains from/to and construct search modes and names stance and displayable_only as filters, but it omits min_grade and limit entirely. This is partial compensation for an otherwise undocumented schema.

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

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

The description clearly states a specific verb ('Search') and resource ('evidence quotes'), and defines the two search modes: construct→construct relationships via from/to, or single-construct statements. It is specific enough to distinguish from general citation or evidence tools, though it does not explicitly name a sibling alternative.

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 context by stating this is 'the display layer for the metric profile page + book,' which implies when it should be used. It does not explicitly state when not to use it or name alternatives, but the intended use case 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavior beyond that: unresolved joins return an honestly empty linked_constructs[] rather than an error, and all three entry paths are currently ungated. That is real operational context, though it is buried in registry/cert jargon.

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

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

The core purpose is correctly front-loaded in sentence one, but the remainder is weighed down by registry certificates, join IDs (MF-711, PRN-281), and landing dates that an agent does not need in order to call the tool. The 'resolves honestly empty the same way' idea is also stated twice.

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 explanation is not required, and the description does cover the read-only, no-error-on-miss behavior. However, for a five-parameter trace tool with zero required parameters it never states which entry points are mutually exclusive or required, and it omits the two limit parameters entirely, leaving the invocation contract 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 0%, so the description carries the full burden. It documents the accepted id shape and resolution path for problem_id and condition_id, leaves construct_id only implicit, and says nothing at all about limit_priors or limit_interventions. With two of five parameters completely unexplained and no indication that at least one entry point is required, the compensation is only partial.

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 gives a specific verb (retrieve) and resource (full causal chain from construct/condition/problem to interventions, with evidence grades per hop), which is far more than a restatement of the name. It is distinguishable in kind from lookup/search siblings, but it never names or contrasts with the closest sibling, principia.evidence.for, so the agent is left to infer the boundary.

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

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

Usage is only implied: the description enumerates the three entry points (problem_id, condition_id, construct_id) and their id formats, from which an agent can infer when each applies. There is no explicit when-to-use vs when-not, no guidance against principia.evidence.for or principia.constructs.resolve, and no statement of prerequisites.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds only the filtering behavior ('narrows to instruments covering a given construct') and the term 'rows', but nothing about pagination, ordering, ownership scope, or response size.

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

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

Two tight sentences with the action front-loaded and no wasted words. The filter clarification earns its place, though several parameters are undocumented—this is under-specification rather than verbosity.

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 5-parameter, 0%-schema-coverage list tool with no required parameters, the description covers only one filter; limit/offset and license/owned semantics are missing. The presence of an output schema reduces the need to describe return shape, but the calling semantics remain 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 0%, so the description needed to clarify the parameters; it only explains construct_id. The remaining four parameters (limit, offset, owned, license) are left entirely to schema names, and their semantics are absent.

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

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

The description uses a specific verb ('List') and resource ('InstrumentCard rows') and adds a meaningful optional filter, so an agent knows what it returns. It doesn't explicitly contrast with sibling search/lookup tools, but the list/search/lookup naming convention plus 'rows' makes its role reasonably clear.

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

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

The description implies the main use case: fetch instrument cards, optionally narrowed by construct_id. It gives no guidance about when to prefer this over principia.instruments.search or principia.instruments.lookup, nor any exclusions or preconditions.

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, and the description adds a non-obvious behavioral detail: unknown IDs return found:false rather than an error or empty result. This is useful operational context beyond what annotations and the schema provide.

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-load the action and parameter, with no filler. The second sentence adds a high-value behavioral fact without bloating the description.

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

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

For a one-parameter read-only lookup with an output schema, the description covers the essential behavior: exact lookup by instrument ID and the not-found outcome. Nothing critical is missing for an agent to select and invoke the tool correctly; the output schema covers return structure.

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 provides no description for the sole id parameter (0% coverage), so the description must fill that gap. 'by instrument_id' tells the agent that id is the instrument's unique identifier, and 'unknown ids return found:false' further clarifies its role; for a single simple parameter this is sufficient semantic compensation.

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: 'Lookup one instrument by instrument_id,' which clearly identifies the tool's function and distinguishes it from the list and search siblings by specifying a single exact-key lookup. The added 'Unknown ids return found:false' reinforces that this is an exact ID query, not a fuzzy 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?

The phrase 'by instrument_id' clearly establishes the usage context: use this tool when you have an exact instrument identifier and need one matching record. It does not explicitly name alternatives or when-not-to-use, so it stops short of a 5, but the lookup-by-id framing gives an agent clear guidance relative to search/list siblings.

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

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

The description adds behavioral context by specifying the search scope: instrument_name, developer, and constructs_covered. The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Missing details like matching semantics, case sensitivity, or default limits keep this from being a higher score.

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

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

A single sentence with no filler. The key term 'Keyword search' is front-loaded, and every word contributes meaning.

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

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

For a simple search tool with an output schema and safety annotations, the description is adequate for a basic invocation. However, it lacks routing guidance relative to sibling tools and provides no detail on result ordering, limit defaults, or search matching behavior.

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 description defines the meaning of q as a keyword applied to instrument_name, developer, and constructs_covered, which is useful since schema description coverage is 0%. The limit parameter is not explained, though its schema does provide type and range constraints. Overall, the description partially compensates for the schema's missing descriptions but not fully.

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

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

The description clearly states a specific verb and resource: keyword search over instruments. It also names the three fields searched, which gives concrete meaning beyond the tool name. However, it does not explicitly differentiate itself from sibling instruments.list or instruments.lookup, so it falls short of a 5.

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

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

The phrase 'Keyword search' implies the tool should be used when a keyword-based query over specific fields is needed. However, there is no explicit guidance about when to prefer this over instruments.list or instruments.lookup, and no alternatives are named.

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 the safety profile is covered. The description adds useful behavioral detail about the return shape (`{matches, total, note?}`) and the 0-or-1 match cardinality, which goes 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?

The description is two tightly written sentences with no filler. The primary action is front-loaded, and the return-shape note earns its place by clarifying cardinality and parity with sibling lookup tools.

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-ID lookup, the description covers the core behavior, return shape, and match cardinality, while the output schema covers field details. The main completeness gap is the parameter-name discrepancy and the absence of any note about the `id` vs `intervention_id` mapping.

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 0%, so the description must carry the parameter meaning. It refers to `intervention_id`, but the actual schema property is `id`, creating a potential mismatch that could lead an agent to pass the wrong key. It also does not explain where the ID comes from or its format.

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 ('Look up') and resource ('one Intervention') with a clear identifier (`intervention_id`). It clearly distinguishes this from the sibling `interventions.search` by framing it as a single-record lookup by ID.

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

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

The description implies the right usage context: use this when you have a specific intervention ID and need exactly one Intervention. It does not explicitly name alternatives or say when not to use it, but the singular lookup-by-ID language makes the context 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description redundantly confirms read-only while adding the curator-policy D4 reference. It also explains the non-obvious problem_id resolution path, but does not cover auth, rate limits, or result behavior beyond what the output schema provides.

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 opening clause, and the dense parenthetical definitions are necessary for the complex filter semantics rather than filler. The single long first sentence is heavy but structured; the final read-only note is partly redundant with annotations.

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

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

The description is strong on filter semantics, and annotations plus an output schema cover safety and return structure, reducing what the description must carry. It still omits limit/pagination behavior and any routing guidance between this search tool and the sibling interventions.lookup, leaving clear gaps for a tool of 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 description coverage is 0%, so the description carries the full burden and does so well for four of five parameters: construct_id matching against targets_constructs[], problem_id as a ProblemFrame pf.* address resolved through the MF-711 join, modality matching delivery_modality[], and cost_band exact match on typical_cost_band. The limit parameter is not described, though its schema constraints (max 500, exclusiveMinimum 0) make its basic meaning inferable.

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

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

States a specific verb and resource ('Search Intervention rows') and details the composite filtering behavior. However, it does not distinguish this search tool from the sibling principia.interventions.lookup, so an agent must infer the difference from the tool name alone.

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 explains that filters AND together and any subset is valid, which is useful parameter-combination guidance. It gives no explicit when-to-use guidance, no exclusions, and never names the alternative lookup tool for fetching a single Intervention.

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, non-destructive operation, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the SPEC §6/Q4 licensing rule that non-public-domain/open licenses yield status:'restricted'. It stops short of describing error behavior for unknown ids.

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

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

Two dense sentences, front-loaded with the core action before the licensing caveat, with no filler. The SPEC citation is terse but functional.

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 documentation is not required, and the description covers purpose plus a key conditional behavior. What is missing is routing guidance against items.search and the response for a nonexistent id, which keeps it from being fully complete.

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

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

Schema description coverage is 0%, so the description must carry the parameter. It supplies the meaning 'item_id' (the survey item identifier), but the schema actually names the parameter 'id' and requires minLength 1 — the naming mismatch leaves the mapping slightly fuzzy rather than fully clarified.

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 ('Lookup one survey item by item_id'), and the singular 'one' signals a single-record fetch distinct from a search tool. It does not name items.search as the alternative, but the resource and cardinality are unambiguous.

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

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

The phrase 'one survey item by item_id' implies use when you already have an identifier and want a single record, which indirectly contrasts with principia.items.search. However, it never states when to prefer this over search or what happens on a miss, so guidance is only implied.

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 read-only and non-destructive behavior, so the description does not need to restate that. It adds meaningful behavioral context beyond annotations: restricted items have their text fields stripped and restricted_count reports how many. This is important non-obvious behavior for interpreting results.

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

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

Two sentences with no filler. The core action is front-loaded, and the restricted-item caveat is delivered efficiently. Every word earns its place.

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

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

For a simple read-only text search with an output schema present, the description covers the essential behavior, including the main quirk about restricted items. It doesn't provide usage guidance or search syntax details, but annotations and output schema carry some of that burden, so the description is reasonably complete.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that 'q' is a text query and mentions restricted_count as an output signal, but it does not explain search matching semantics or add detail about the limit parameter beyond what the schema already provides. Partial compensation but not complete.

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?

Description states a specific action ('Search items by text') with a clear resource ('items') and mechanism. It also distinguishes itself from lookup-style siblings and adds a unique scoping detail about restricted items. The verb+resource pairing leaves little ambiguity about what this tool does.

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

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

The description implies this tool is for text-based search over items, which is reasonably clear given sibling names like lookup and list. However, it never explicitly states when to choose this over principia.items.lookup or other search tools, and offers no exclusions or alternative 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=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context beyond the filtering semantics, but this is acceptable for a simple read-only list operation 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?

The description is two short sentences with no filler or repetition. The core operation is front-loaded, and the entity_kind clarification 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?

The tool is simple, has an output schema, and annotations cover safety. However, the description omits default behavior when entity_kind is absent and gives no guidance relative to sibling tools, leaving minor gaps for an agent deciding how to invoke 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?

Schema description coverage is 0%, and the description does compensate for entity_kind by explaining that it selects between scientific_construct and operational_metric. However, it does not add any meaning for limit or offset, although those are fairly self-explanatory from their names and schema bounds.

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 'Measure rows' and clarifies the entity_kind filter's two possible values. It is clear, but it does not explicitly distinguish itself from sibling tools such as principia.measures.lookup or principia.constructs.list.

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

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

No explicit when-to-use or alternative routing guidance is provided. The entity_kind hint explains filtering options but does not state when to use this list endpoint instead of a lookup/search sibling, nor what happens if no filter is supplied.

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, covering the safety profile. The description adds valuable behavioral detail by stating that 'Unknown ids return found:false,' which is not available from annotations alone. This is a meaningful addition for an agent handling missing results.

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 short sentences with no filler. The primary action is front-loaded, and the additional not-found behavior is stated in a concise, direct second sentence. Every word earns its place.

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

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

For a simple one-parameter lookup with a readOnly annotation and an output schema present, the description is complete. It covers the core operation, the parameter's meaning, and the edge case of unknown IDs. Nothing critical is missing for an agent to invoke this 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 0%, so the description carries the burden of explaining the parameter. It clarifies that 'id' refers to a measure_id, giving semantic meaning beyond the raw schema field. For a single simple string parameter, this is adequate compensation.

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: 'Lookup one Measure by measure_id.' It clearly distinguishes this from list/search siblings by emphasizing a single ID-based lookup. The behavior for unknown IDs is also specified, making the tool's purpose unambiguous.

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

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

The phrase 'Lookup one Measure by measure_id' clearly implies this is the tool to use when you have a single known measure ID, as opposed to list or search tools. It does not explicitly name alternatives or exclusions, but the context from sibling names makes the usage clear enough.

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

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

Annotations already declare the operation read-only and non-destructive, so the description does not contradict them. However, it adds no behavioral detail beyond that, such as pagination behavior, result scope, or whether all rows are returned; the parenthetical only clarifies domain meaning.

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

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

The description is a single, concise sentence with no filler. The parenthetical adds relevant clarification without bloating the text, and the key action 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?

The presence of an output schema and read-only annotations reduces the burden on the description, but the ambiguity with `theoretical_models.list` and the lack of pagination semantics leave important selection and invocation gaps. An agent may not be able to reliably choose this over the sibling list tool.

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

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

Schema description coverage is 0%, and the description provides no explanation of the `limit` and `offset` parameters. Since the schema itself also lacks descriptions, these parameters are effectively undocumented, and the description does nothing to compensate.

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

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

The description uses a clear verb-resource pair, 'List Model rows', and adds a useful parenthetical defining models as 'theoretical / structural frameworks.' However, it does not explicitly distinguish this list from the sibling `theoretical_models.list`, leaving some ambiguity about the exact entity boundary.

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

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

There is no guidance about when to use this tool versus alternatives like `models.lookup`, `models.search`, or `theoretical_models.list`. The list semantics are implied by the name and verb, but no explicit when/when-not or alternative routing is provided.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral detail: unknown IDs return 'found:false' rather than throwing or returning an empty result. There is no contradiction with 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?

The entire description is one focused sentence. It states the action, the target resource, the lookup key, and the not-found behavior with no filler or redundancy. Every word earns its place.

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

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

For a simple single-parameter lookup tool, the description is complete: it names the input semantics, the operation's scope, and the important edge-case response. An output schema exists, and annotations already capture the read-only, non-destructive nature. Nothing essential is missing for an agent to invoke this 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?

The input schema only provides a bare 'id' field with no description, and schema description coverage is 0%. The description clarifies that the id refers to a model_id, which adds meaning beyond the schema. However, it stops short of describing the expected format or how the model_id should be obtained, so it only partially compensates for the missing parameter documentation.

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

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

The description uses a specific verb ('Lookup'), a specific resource ('one Model'), and the lookup key ('model_id'). This clearly distinguishes it from the sibling list/search tools, and the not-found behavior ('Unknown ids return found:false') adds further precision.

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 makes the intended use clear: retrieve a single model by its ID. It signals the relevant situation (you have a model_id) and even covers the edge case of an unknown ID. It does not explicitly contrast with models.list or models.search, but the one-model-by-ID phrasing provides clear contextual guidance.

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

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

Annotations already declare the tool read-only and non-destructive, so the description only needs to add behavioral context. It adds the search scope across model_name and description, but does not disclose matching semantics, case sensitivity, ordering, 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?

The description is a single sentence with no filler, and the key scoping information (which fields are searched) is front-loaded. It is terse but appropriately sized for a simple search operation.

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

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

For an annotated read-only search tool with an output schema, the description is minimally viable but leaves gaps: it does not mention result ordering, limit behavior, or how this search differs from related search tools. It is adequate but not comprehensive.

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 0%, so the description must compensate. It implies that the q parameter is the keyword applied to model_name + description, which adds meaning, but it never explicitly names q or explains the limit parameter beyond what the schema constraints provide.

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

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

The description clearly states the action (keyword search), the resource (models), and the specific fields searched (model_name + description). This is specific enough to distinguish it from list/lookup operations, though it does not explicitly reference sibling 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?

No guidance is given about when to use this versus models.list, models.lookup, or theoretical_models.search. The keyword-search intent is implied by the tool name and one-line description, but there are no explicit conditions, exclusions, or alternative recommendations.

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 mark the tool as read-only and non-destructive, and the description reinforces this with 'Read-only'. It adds useful behavioral context by specifying the canonical subset and the sort order by foundational publication year. It does not discuss pagination behavior, but this is a minor gap given 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?

The description is only three short sentences, each earning its place: the scope with examples, the sort order, and the read-only nature. There is no filler or redundant elaboration.

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

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

For a simple read-only listing tool with two optional pagination parameters and an output schema, the description captures the essential scope, the canonical examples, the ordering, and the safety profile. Nothing critical 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 description coverage is 0%, so the description must compensate for the two parameters, but it never mentions limit or offset. The parameter names and constraints are fairly self-explanatory, but the description adds no semantic meaning beyond the schema.

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

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

The description states a specific verb and resource: 'List canonical theoretical models', and reinforces the scope with concrete examples (JD-R, COR, SDT, AET, JCM, etc.). It also notes the sort order, making this clearly distinct from sibling lookup/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?

The description gives no explicit guidance on when to choose this tool over alternatives. It does not say 'use lookup for a specific model' or 'use search when filtering by criteria'; the only usage signal is the verb 'list', which must be inferred.

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 that the tool is read-only and non-destructive. The description adds useful behavioral context by specifying what the lookup returns: canonical constructs, canonical relations with predicates, descendant per-study models, and foundational citations. This goes beyond annotation coverage without contradicting it.

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 filler. The first sentence states the action and key parameter; the second compactly enumerates the return contents. 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 lookup tool with an output schema and safety annotations already provided, the description is complete. The agent knows the ID format, the resource type, and what to expect in the response. No critical 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?

The schema provides only 'id' with minLength 1, so the description meaningfully compensates by explaining the ID identifies a CanonicalTheoreticalModel and giving a real-world example ('theory.jd_r'). This is valuable guidance beyond the bare schema.

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

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

The description uses a specific verb and resource ('Look up one CanonicalTheoreticalModel by id') and provides a concrete example ID. This clearly distinguishes it from list/search siblings, which operate over multiple models rather than fetching a single one.

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

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

The phrase 'by id' gives clear context: this tool is appropriate when the agent already has a specific CanonicalTheoreticalModel identifier. It does not explicitly name alternatives or exclusion criteria, but the usage situation is unambiguous and sufficient for correct tool selection.

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 mark the tool as read-only and non-destructive. The description adds meaningful behavioral detail by specifying the searched fields and explaining both optional filters: invokes_construct_id for construct-invoking theories and field_domain as the classification axis. 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 concise, front-loaded sentences: the core action comes first, followed by optional filters. There is no redundant phrasing or filler.

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

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

Given the annotations, output schema, and simple parameter set, the description covers what is searched and what the filters mean. The only notable gap is the absence of explicit guidance on when to choose this tool over sibling search/list/lookup variants.

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 0%, so the description carries the semantic load. It explains q as keyword over name/summary/constructs and glosses invokes_construct_id and field_domain. Only limit is left to the schema's numeric constraints, which are simple enough.

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

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

The description clearly states a verb and resource: keyword search over theoretical models, scoped to name/summary/constructs. It is unambiguous about what is searched, though it does not explicitly distinguish itself from sibling search tools like principia.models.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?

The description gives a clear usage context: use it for keyword search over theoretical models with optional filters. It does not, however, explain when to prefer this tool over the sibling list or lookup tools, nor does it name alternatives or exclusions.

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