Kaal Corpus: Verifiable Claim Layer

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context: the report's scope (single author), that it asserts no ranking, and that topic counts overlap. This goes beyond annotations to inform agent 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 extremely concise: two paragraphs with a clear front-loaded purpose statement and a second paragraph for usage context. Every sentence adds value, and there is 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?

Given zero parameters and the presence of an output schema, the description fully covers what the tool does and its limitations. It provides all necessary context for an agent to invoke correctly without ambiguity.

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

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

The input schema has zero parameters, so baseline is 4. No additional parameter information needed.

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 reports specific information about the claim layer: total claims, works covered, publication span, failure-mode counts, and coverage per topic. It distinctively focuses on a single author's corpus, differentiating from siblings like 'corpus_overview' or 'claims_on_topic'.

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

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

The description explicitly states that the coverage is for one author's corpus and that it is not a field survey with ranking, providing clear context for when to use it. It could be improved by directly contrasting with sibling tools like 'corpus_overview', but the limitations are well-stated.

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

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

Annotations already define readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the important behavior of requiring a prior call to claim_layer_overview, which is not covered by 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, front-loaded with the core purpose, example tags, and a crucial usage hint. No extraneous information.

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

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

With only two parameters and an output schema available, the description covers all essential information: what the tool does, example inputs, and a prerequisite step. It is complete for this simple 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%, but the description provides example values for the 'topic' parameter, aiding understanding. The 'limit' parameter is not described, though its default and purpose are common knowledge. The description partially compensates for the missing 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 the tool returns claims for a given topic tag, provides example tags, and directs the user to a sibling tool for exploring available tags. This effectively distinguishes it from other tools.

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

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

Explicitly instructs users to call claim_layer_overview first to discover valid topic tags and their prevalence, providing clear when-to-use guidance and a necessary prerequisite.

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, indicating a safe read operation. The description adds content details but doesn't disclose additional behavioral traits beyond what annotations 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?

Single sentence efficiently lists key outputs and usage context with no wasted words. Front-loaded with purpose.

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 no parameters, rich annotations, and an output schema, the description covers the tool's purpose and usage context fully. Sibling tool differentiation is implied.

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?

No parameters exist, and schema coverage is 100%. The description doesn't need to add param info; baseline for zero parameters is 4.

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 'Summarise' and identifies the resource 'the corpus', listing concrete outputs (total works, coverage by year, etc.). It also distinguishes from siblings by recommending it as a first call when unsure of contents.

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

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

Explicitly states 'Call this first when you are unsure what the corpus contains', providing clear when-to-use guidance. No exclusionary advice given, but the context is sufficient.

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, idempotentHint, etc. The description adds what the tool returns (claim, quote, scope, topics, edges, pdf hash, citation) and notes field name compatibility with search_claims, which is valuable beyond annotations.

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

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

Two sentences, each earning its place: first states purpose and gives examples, second details return fields and chainability. No wasted 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?

Given the simple single-parameter tool and existence of output schema, the description covers the purpose, parameter format, and return compatibility. No gaps remain for effective use.

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 has 0% coverage for claim_id. The description compensates by giving concrete examples ('617681-001', 'kaal:claim:617681-001') and explaining the parameter's role, adding meaning 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 clearly states 'Resolve one claim by id' – a specific verb-resource pair. It distinguishes from sibling tools like search_claims by focusing on a single record and providing ID format examples.

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?

Describes when to use: when you have a claim ID. Mentions ID formats and compatibility with search_claims results. Lacks explicit 'do not use for bulk queries' or contrast with siblings like search_claims.

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, destructiveHint, and idempotentHint. The description adds useful behavioral context about included output elements (formatted citation, SSRN URL, published sha256) 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 sentences with no redundancy. First sentence states purpose and identifiers, second lists included output features. Every word earns its place.

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

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

Given the output schema exists (not shown but present), the description adequately covers the tool's function and key output fields. Could be slightly more specific about identifier formats but is sufficient.

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 coverage, the description compensates by explaining that paper_id can be a corpus ID, SSRN ID, or exact title, adding meaning beyond the schema's bare string type.

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 verb 'retrieve' and the resource 'one work's complete metadata', specifying the allowed identifiers (corpus id, SSRN id, or exact title). This distinguishes it from sibling tools like search_papers which handle batch or query-based retrieval.

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 implicitly indicates when to use (when you have a specific identifier) but does not explicitly exclude search scenarios or mention alternatives like search_papers for broader queries.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds that the position is 'public' and describes acceptable ID formats, but this is modest additional context. 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?

One concise sentence front-loaded with the action verb. It includes an example and a legitimate alternative input format without any fluff.

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

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

For a simple get-by-id tool with one parameter and an output schema present, the description is mostly complete. It explains the input format and public scope, though it does not mention what happens if the position is not found, a minor 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 schema only defines position_id as a string. The description adds the exact ID format with an example and explains that a date-sequence suffix is also accepted, providing essential meaning beyond the schema. This is particularly valuable given 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?

The description uses the specific verb 'Resolve' and names the resource 'public position', making it clear this tool fetches a single position by ID. It distinguishes itself from search siblings by focusing on direct resolution rather than searching.

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 context is clear: use this when you have a position ID (full id or suffix). However, it does not explicitly mention alternatives like search_positions or exclusions, so it misses the 'when-not-to-use' guidance that would earn a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds the identifier format detail but does not disclose other behavioral traits such as error handling or return behavior, which would add further value beyond annotations.

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

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

The description is a single sentence that is front-loaded and contains no redundant information. Every word contributes to the understanding of the tool's purpose and parameter usage.

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

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

For a simple get-style tool with one parameter and an output schema present, the description is sufficiently complete. It covers the key input requirement and relies on annotations for safety context, though it could mention behavior when the claim is not found for total completeness.

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 describes claim_id as a string with no additional description. The description compensates fully by specifying that the parameter accepts either a full identifier or a three-digit sequence, providing concrete guidance on valid input formats.

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 specifies the tool's function: it resolves one TrustCarry Protocol v0.3 research claim using a full identifier or three-digit sequence. This distinguishes it from sibling tools like get_claim or search_research_claims by both the specific resource type and the identification method.

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 appropriate usage context: use when you have a claim's full identifier or three-digit sequence. It provides clear context for when the tool is applicable, though it does not explicitly mention alternative tools for cases when the identifier is unknown.

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 read-only, idempotent, non-destructive, and open-world hints. The description adds the identifier types (full or three-digit sequence), which is more about parameter semantics than behavioral disclosure. No contradictions, but little additional behavioral context beyond annotations.

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

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

A single, well-front-loaded sentence that states the action, resource, and identification method without any waste. It is perfectly concise.

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 with rich annotations and an output schema, the description covers the core resolution method. It doesn't explain domain context or when to prefer it over list_research_observations, but complexity is low.

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 defines observation_id as a string without format details. The description clarifies that the identifier can be a full identifier or a three-digit sequence, adding meaningful semantic value beyond the schema. For a single parameter with 0% schema coverage, this is a solid 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 uses the specific verb 'Resolve' and identifies the resource as 'one TrustCarry Protocol v0.3 internal software observation', with a clear lookup method by identifier or sequence. This distinguishes it from sibling getters like get_claim and get_paper.

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 usage for retrieving a single observation by identifier, placing it among other getter tools. It does not explicitly name alternatives or exclusions, but the context is clear enough to differentiate from list_research_observations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true. Description adds that it returns citation instruction and should be called before quoting, which adds minor behavioral context.

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

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

Two sentences with no wasted words, directly stating purpose and usage hint.

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?

Minimally adequate: covers purpose and usage, but lacks explicit parameter explanation. Output schema exists, so return values are documented elsewhere.

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

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

Schema coverage is 0% and description does not explain the paper_id parameter. The mention 'if one is named' only implicitly refers to it, which is insufficient for a low-coverage 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 clearly states the tool returns citation instructions and formatted citation for a specific work, which is distinct from sibling tools that handle papers, search, etc.

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

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

Explicitly says 'Call this before quoting anything', providing clear usage context. Does not compare to alternatives but context is sufficient.

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 context beyond these hints by noting that the observations 'report synthetic-fixture behavior and have not been independently reproduced,' which informs the user about data reliability and provenance—a useful caveat not present in 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. The first sentence front-loads the action and object. The second sentence adds a critical caveat in minimal words. There is no fluff or repetition of schema 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 tool has no parameters, an output schema exists (per context signals), and annotations cover safety, the description is complete. It states what the tool returns (9 items) and adds the caveat about synthetic-fixture behavior. No additional return-value explanation is needed because the output schema is present.

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

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

The tool has 0 parameters, and schema coverage is 100% (trivially). With no parameters to describe, the baseline is 4. The description does not attempt to describe parameters because none exist, which is appropriate.

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

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

The description begins with a specific verb 'List' and identifies the exact resource: 'the 9 TrustCarry Protocol v0.3 internal software observations.' This clearly distinguishes it from sibling tools like get_research_observation (which fetches a single observation) and search_research_claims (which searches a different resource).

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

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

The description implicitly communicates usage—this lists all internal observations—but does not explicitly state when to use it over alternatives or when not to use it. There are no exclusions or comparisons to sibling tools, so guidance is limited to what can 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover the behavioral safety profile. The description adds the nuance that it returns every work for a year and the rationale for chronological tracking, but no further details like pagination or ordering.

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 long, front-loaded with the action and then the usage context. It is concise but could potentially include more parameter details without being overly verbose.

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

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

Given the tool's simplicity (one parameter, output schema present, low complexity), the description covers the main purpose and use case adequately. It lacks parameter specifics but remains functional for an 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?

With 0% schema description coverage, the burden is on the description to explain the 'year' parameter. However, the description only mentions 'given year' without specifying format, range, or constraints, leaving ambiguity despite the integer type.

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 lists every work published in a given year, with a specific verb and resource. It differentiates from siblings like search_papers and corpus_overview by providing a use case: tracing a position over time.

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

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

The description explicitly advises when to use this tool (to trace development over time) rather than reading the corpus as a flat set. It implies not for general searches or overviews, though it does not list explicit alternatives.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by specifying 'public positions' and the matching behavior: it follows the published topic shard and does not infer semantic relationships. This gives concrete context about data scope and algorithm that annotations do not 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?

The description is two sentences, with the primary action in the first sentence and a clarifying behavioral note in the second. Every word earns its place; 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?

The tool is simple (2 params, output schema present), and the description covers the core purpose and behavioral constraint. It lacks an explicit alternative-tool reference, but the annotations and output schema provide sufficient contextual coverage for the agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that 'topic' refers to an explicit tag, directly clarifying the required parameter's meaning. The optional 'limit' is not explained, but its name and default in the schema make it self-evident.

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 starts with a clear verb and resource: 'Return public positions carrying an explicit topic tag.' It further distinguishes itself from semantic search tools by stating it 'does not infer semantic relationships,' which differentiates it from siblings like search_positions or claims_on_topic.

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 this tool: when you need positions with explicit, non-inferred topic tags. It explicitly clarifies that it follows the published topic shard and avoids semantic inference, giving the agent a basis to choose this over search tools, though it does not name alternative tools directly.

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

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

Beyond annotations (readOnlyHint, etc.), it discloses how queries are processed (stopwords stripped, exact phrase treatment), match modes, and claim_type filters. This adds valuable behavioral context beyond the annotation 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?

The description is compact yet informative, with clear sections for purpose, query processing, match modes, and filters. No redundant sentences.

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 output schema exists, the description covers query behavior, match options, and filters well. However, it fails to explain limit and failure_modes_only, leaving minor gaps.

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

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

With 0% schema coverage, the description explains match and claim_type but omits limit, query (processing only), and failure_modes_only. It adds moderate value for some parameters but leaves others undocumented.

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 it searches individual assertions rather than whole papers and specifies what it returns (verbatim source quote, scope conditions, sha256). This distinguishes it from sibling tools like search_papers.

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

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

It provides guidance on when to use (for claims, not papers) and explains query processing (stopword stripping) and match modes. However, it does not explicitly compare with all siblings, missing some 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context: returns ranked works with specific fields (title, year, citation, SSRN link, sha256). This adds value beyond annotations.

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

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

Two concise sentences, front-loaded with the main verb and resource. No unnecessary words, efficiently conveys purpose, usage, and output.

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 no output schema provided but indicated, description covers input (query) and output format (fields). Missing detail on limit parameter, but for a simple search tool, it is reasonably complete. Sibling tools help contextualize.

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% with no descriptions. Description only mentions the 'query' parameter (search by topic, title, keyword) but does not explain 'limit' parameter. Since description must compensate, it fails to fully document parameters.

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 clearly states the verb 'Search' and the resource 'scholarly corpus'. It specifies search criteria (by topic, title, keyword) and distinguishes from siblings like 'get_paper' (individual paper) and 'corpus_overview' by mentioning Kaal's published position.

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?

Description explicitly states when to use: 'for questions about Kaal's published position on a subject, or to find work to cite'. It does not state when not to use or mention alternatives, but the sibling tools imply alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, which cover the safety and side-effect profile. The description adds valuable behavioral context beyond annotations: that results preserve the separate scholarly-claim relation and evidence limitation, and that a position must never be presented as a verbatim paper claim. This is a critical handling instruction for an AI agent to avoid misrepresentation.

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 zero wasted words. The first sentence states the function and scope, and the second adds a crucial interpretational caveat. It is front-loaded with the primary purpose and all information is relevant.

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

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

With an output schema present, the return value details are covered externally. The description covers the tool's input semantics, intended use case, and a key behavioral caveat. It does not mention pagination or result ordering, but these are less critical for a read-only search tool with output schema provided. The main gap is that it doesn't explicitly state what 'positions' are or how they differ from claims, but sibling tools and the context signal compensate somewhat.

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%, meaning the description does not explicitly document the query or limit parameters. The phrase 'by natural-language terms' implicitly describes the 'query' parameter, but the 'limit' parameter is completely unaddressed. Since there are only two parameters and one is required, the description should compensate more for the lack of schema-level descriptions, especially for the limit parameter whose semantics (maximum number of results?) are only inferable from its name.

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?

Purpose is crystal clear: 'Search public owner-authorized Kaal response positions by natural-language terms.' The verb 'search' plus the specific resource type ('positions') with qualifiers (public, owner-authorized) and method (natural-language) precisely defines what the tool does. It also distinguishes from siblings like search_claims and search_papers by focusing on positions, and the caveat about not presenting positions as verbatim paper claims adds a unique distinguishing 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 it: for searching public positions using natural language, with an important caveat about handling scholarly-claim relations. It does not explicitly name alternative tools (e.g., positions_on_topic or search_claims) or provide exclusion criteria, but the 'public owner-authorized' qualifier and focus on positions provide clear context that this is the tool for position-specific natural-language searches.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds no behavioral context beyond purpose and guidance, which is acceptable but not additive.

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

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

Two sentences, front-loaded with purpose, no wasted words. Highly efficient.

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 purpose and usage guidelines. It does not mention output, but an output schema exists. Minimal gap given tool simplicity 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%, and the description does not explain param meanings. 'query' and 'limit' are self-explanatory from schema names, but with zero coverage the description should compensate; it does not.

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 searches blog posts for 'shorter, faster-moving analysis' and distinguishes it from search_papers for settled views. This provides a specific verb+resource and explicit sibling differentiation.

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

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

The description gives explicit when-to-use (shorter analysis) and when-not-to-use (settled views, prefer search_papers). It names the alternative tool and provides context for choice.

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, idempotent, and non-destructive behavior. The description adds useful context about provenance (unpublished source manuscript), licensing (CC BY 4.0), and scope exclusion, enriching the agent's understanding beyond annotation flags.

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

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

Two sentences, front-loaded with the core action and distinguishing scope. No redundant or filler content.

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

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

With an output schema present and simple parameters, the description covers the key differentiators (scope, provenance) and does not need to describe return format. It is complete enough for selecting and invoking this tool, though it could clarify 'research claims' further.

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

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

Schema provides no parameter descriptions (0% coverage), and the description does not explain the query semantics or limit behavior. While query and limit are self-explanatory, the description fails to compensate for the lack of schema 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?

Description clearly identifies the tool as a search over a specific subset of claims (77 TrustCarry Protocol v0.3 author-affirmed research claims), distinguishing it from the broader scholarly claim layer and sibling tools like search_claims.

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?

Description explicitly scopes usage to a particular claim subset ('only the 77...') and notes these are not part of the 5,113 scholarly claim layer, signaling when to prefer this tool over general search_claims. It does not explicitly name alternatives, but the scope differentiation is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral context: it proves you have the author's bytes, not a mirror or regenerated file. No contradictions 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 that are front-loaded and efficient. First sentence states core function; second provides usage guidance. No unnecessary 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?

For a simple tool with one parameter and an output schema, the description covers purpose, when to use, and why. Could mention what the response looks like, but output schema likely provides that.

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 fully explains the parameter 'sha256' as a hash computed over a PDF. It adds meaning beyond the schema's type declaration by linking it to the verification purpose.

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 checks if a SHA256 computed over a PDF matches a published work. It provides specific context about trustworthiness and distinguishes itself from sibling tools like get_paper or search_papers.

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

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

Explicitly tells when to use (before quoting from untrusted sources) and why (proves you have the author's bytes). Implies alternatives (trusted sources like SSRN or wulfkaal.com) but does not name sibling alternatives.

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