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 establish readOnlyHint and non-destructive behavior. The description adds valuable non-obvious behavioral context: the tool is currently empty until a synthesis engine ships, and it accepts two distinct lookup key forms. It does not cover edge cases like both id and triple being supplied, but it goes beyond the annotations usefully.

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 one compact sentence that front-loads the operation and resource, then states the accepted lookup keys and the availability caveat. Every clause earns its place and there is no redundant restating of the tool name or schema.

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 core lookup semantics and current empty state, and an output schema exists to handle return-value details. However, it leaves the sample_culture parameter unexplained and does not offer routing guidance toward canonical_priors.search for broader needs, making invocation guidance 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 must carry the parameter-semantics burden. It usefully maps id and the from_construct_id/predicate/to_construct_id group into two lookup paths, but it completely omits sample_culture, which remains unexplained. The schema itself provides no descriptions, leaving a real 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 a specific verb ('Lookup'), a specific resource ('synthesized Bayesian prior'), and the exact identifiers accepted: by id OR by a triple of from_construct_id, predicate, to_construct_id. This clearly distinguishes it from sibling search/list tools by signaling an exact-lookup operation.

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 guidance on when to use the tool: when you have a prior id or the exact (from_construct_id, predicate, to_construct_id) combination. It also provides the important caveat that it is currently empty until PRN-021 ships. However, it does not explicitly mention alternatives like canonical_priors.search or say when not to use this tool.

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

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

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 establish readOnly and non-destructive behavior; the description adds the important behavioral trait that unknown ids resolve to found:false rather than an error. This soft-validation behavior is meaningful operational detail beyond the structured annotations.

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

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

A single sentence delivers the action, target, key, and edge-case behavior with no filler. The most decision-relevant information is front-loaded.

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

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

For a one-parameter read-only lookup backed by an output schema, the description covers the essential call semantics and the not-found contract. No critical missing piece is apparent for an agent to invoke it correctly.

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

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

The schema only declares 'id' as a minLength-1 string, with no description. The description compensates by mapping that id to a variable_id and indicating that it selects one canonical construct, which is the core semantic an agent needs.

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'), names the resource ('canonical construct'), and specifies the key ('variable_id'). It contrasts with list/search siblings by emphasizing a single canonical item and explicitly describing the not-found case, making the tool's role 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 conveys a clear use context: retrieve exactly one construct when a variable_id is available, and safely probe existence via found:false. It does not explicitly name alternatives or say when not to use it, but the singular lookup semantics are enough to route an agent away from list/search tools.

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

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

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, and the description adds the useful behavioral context that matching occurs across specific construct fields. However, it does not disclose matching semantics such as substring vs exact, case sensitivity, or default limit behavior. This is adequate but not rich.

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

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

The description is a single focused sentence with no filler. The core operation and search scope are front-loaded, making it 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?

For a simple two-parameter search tool with an output schema and read-only annotations, the description provides the essential information: what is searched and over which fields. It lacks explicit alternative guidance and limit semantics, but these are minor given the tool's simplicity.

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 parameter meaning. The phrase 'keyword search over ... fields' implies that q is the keyword query and clarifies what it matches, but limit is left entirely to its name and schema constraints. Partial compensation only.

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 identifies the resource (constructs), the operation (keyword search), and the exact fields searched (name, definition, alternative_names, variable_codes). This scope distinguishes it from lookup and list siblings, even without explicitly naming them.

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

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

The description gives no guidance on when to prefer this tool over lookup, list, or search tools for other resources. There are no explicit alternatives, exclusions, or conditions, so an agent must infer usage context from the tool 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?

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 mark the tool as safe (readOnlyHint=true, destructiveHint=false). The description adds the 'Phase 2 — empty result today' behavioral caveat, but fails to explain what 'the gating' means, what will happen after Phase 2, or the shape/scoping of the empty result 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?

One short, readable sentence, front-loaded with the core search semantics. It is arguably too terse to carry the needed parameter context, but it wastes no words.

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

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

The note about Phase 2 is unusual and important, but under-explained; critical details about construct ID filters, limit semantics, and the meaning of empty-result behavior are absent. Given six parameters and zero schema coverage, the description is insufficient.

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 six undocumented parameters. It names 'from/to/statistic_type' but not to_construct_id/from_construct_id/limit, and offers no type, format, or semantic meaning beyond the names.

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 identifies a specific verb ('Search') and resource ('EffectSize rows') with the key filter dimensions. It is clear enough to distinguish from siblings in the broader namespace, although it does not explicitly differentiate from other 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 phrase 'Phase 2 — empty result today' gives a critical usage caveat, implying results will be empty now, but it offers no guidance on when to prefer this tool over alternatives, nor does it explain when the gating will lift.

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 cover safety (readOnly and non-destructive), so the description only needs to add extra behavioral context. It does so by disclosing the empty-result phase status and the 'claim subject' semantics, without contradicting annotations.

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

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

Two short sentences carry the core behavior and the critical caveat with no filler; the main verb and resource are 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 output schema covers the return shape and annotations cover safety, so the description does not need to repeat those. However, it omits parameter guidance for limit/subject_type and does not situate this tool relative to evidence.trace or evidence_statements.search, leaving an agent to infer the rest.

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

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

With 0% schema description coverage, the description must explain parameters, but it only clarifies entity_id. limit and subject_type receive no descriptive treatment beyond their property names and enum, leaving part of the call contract 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 names the exact operation ('Return Evidence[] edges') and the selection criterion (entity_id as claim subject), which distinguishes it from generic search/lookup siblings even without naming them. The 'empty result today' caveat further clarifies its current 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 'Phase 2 — empty result today' note implicitly tells an agent not to expect data and to consider alternatives, but no explicit when-to-use or alternative tool (e.g., evidence.trace, evidence_statements.search) is given.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about the corpus being owned, OA-sourced, attributed, and stance-classified, but it does not go further into behaviors like filtering semantics or result handling beyond what the schema already exposes.

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

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

Two tight sentences front-load the main search semantics and then provide the usage context. Every sentence adds value, with no filler or repetition of schema details.

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

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

For a read-only search tool with an output schema and no required parameters, this description is largely complete: it explains query modes, supported filters, and the intended display context. The main gap is min_grade, which is not explained and could affect result filtering.

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

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

With 0% schema description coverage, the description must compensate, and it does explain the core parameters: from/to, construct, stance, and displayable_only. However, it omits min_grade and limit, and min_grade especially is not self-explanatory from the enum alone, leaving a meaningful parameter under-documented.

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

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

The description names a specific verb and resource: searching evidence quotes, with two explicit query modes (construct-to-construct relationship via from/to, or a statement naming a single construct via construct). This clearly distinguishes it from the other search-style sibling tools, which target different resources.

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

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

It gives clear usage context by stating that this is 'the display layer for the metric profile page + book', which tells an agent when this search is appropriate. It does not name alternatives or provide explicit when-not-to-use guidance, but the context is strong enough to guide 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 declare read-only and non-destructive behavior. The description adds substantial behavioral context beyond this: accepted pf.* namespace, frozen registry certificate, construct_id being fully resolved, problem_id depending on a future join table, and condition_id gated on HO-761. This gives the agent realistic expectations about current functionality.

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 the purpose front-loaded and caveats packed into the second sentence. It is appropriately sized, though opaque ticket references like MF-711, HO-761, and the certificate hash add jargon that may not be actionable for an agent.

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

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

The output schema covers return shape and annotations cover safety, but the description does not clarify whether problem_id, construct_id, and condition_id are mutually exclusive or combinable, nor does it explain what the limit parameters precisely affect. For a tool with five optional parameters and partial delivery dependencies, this leaves some ambiguity about the exact invocation contract.

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

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

With schema description coverage at 0%, the description must compensate for the schema's silence. It explains problem_id, construct_id, and condition_id semantics and availability, but it does not describe limit_priors or limit_interventions, which are only inferable from their names and min/max constraints. The ID format guidance is also partial beyond pf.*.

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: 'Retrieve the full causal chain from a construct, condition, or problem to interventions, with evidence grades at each hop.' This clearly defines what the tool does and differentiates it from lookup/search siblings that do not promise chain tracing.

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 provides clear context for when the tool is relevant and includes important availability caveats (condition_id gated, problem_id pending MF-711). However, it does not explicitly name alternatives or state when to prefer this tool over siblings like principia.evidence.for or the various lookup/search tools, leaving routing partly implicit.

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 mark the tool read-only and non-destructive, and the description adds meaningful context: array-inclusion matching, exact matching, AND semantics, subset validity, and the curator-policy label. It does not mention limit defaults or pagination, but those are less critical here given the schema and output 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?

Three compact sentences front-load the purpose and immediately supply the only needed matching semantics and a read-only note. There is no filler or unnecessary repetition of schema details.

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

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

With an output schema present and no required parameters, the description covers the essential call semantics: valid filter combinations, field-level matching rules, AND behavior, and read-only status. An agent can correctly invoke this composite search without needing further inference.

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 property descriptions are absent (0% coverage), and the description compensates well by explaining field-level matching semantics for construct_id, modality, and cost_band. The only gap is `limit`, whose purpose is left to the parameter name 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 opens with a specific verb+resource ('Search Intervention rows') and defines exactly how each filter parameter maps to underlying fields (`targets_constructs[]`, `delivery_modality[]`, `typical_cost_band`). The inclusion-versus-exact-match distinction clearly separates this search from simple lookup siblings.

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

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

The description gives clear context for when to use the tool: filtering by construct, modality, and/or cost band, with 'All filters AND together; any subset is valid.' It does not explicitly contrast with `interventions.lookup` or other alternatives, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context by specifying that SPEC §6/Q4 is enforced, causing restricted status for non-public-domain items. This goes beyond the structured annotations and helps the agent anticipate a possible restricted response. 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 description is two sentences, front-loads the primary purpose, and adds only the critical licensing behavior in the second sentence. Every element earns its place with no redundancy.

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

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

For a simple one-parameter read-only lookup, the description is nearly complete. It explains the singular scope and the key restricted-status behavior. However, with no output schema, it does not describe the response shape, error behavior, or field details, which leaves a minor gap for the agent.

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

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

The schema only provides a string 'id' parameter with no description, and schema description coverage is 0%. The description compensates by identifying the parameter as 'item_id' and clarifying that it refers to a survey item, adding essential meaning beyond the bare schema. A concrete example or format hint is missing, so the score is not a 5.

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

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

The description clearly states the tool's function: lookup one survey item by item_id. It distinguishes itself from sibling search tools by emphasizing 'one' and by id, so an agent can tell this apart from items.search without needing additional context.

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 for when to use the tool: when you need a single survey item and have an item_id. It does not explicitly name alternatives or exclusion conditions, but the singular lookup framing makes the intended use reasonably obvious relative to search siblings.

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

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

Annotations already 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.