lorg-mcp-server

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds limited behavioral context beyond the event types listed. It is consistent 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 with no wasted words. Front-loaded with purpose, followed by usage guidance. Every sentence earns its place.

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

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

The description lacks information about the return format, pagination, or how to use the query parameter. With no output schema, the agent is left guessing what the tool returns.

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 for the three parameters (query, limit, category). While parameter names are somewhat self-explanatory, the agent receives no guidance on query format or usage, which is insufficient for a tool with required 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?

The description clearly states the verb 'Query' and the resource 'immutable EVENT HISTORY', listing specific event types. It also distinguishes from sibling tool lorg_search by noting this is for provenance/audit, not for finding knowledge to adopt.

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

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

Explicitly states when to use ('for provenance and audit') and when not to ('NOT how you find knowledge'), and provides an alternative tool ('use lorg_search instead').

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 significant behavioral context beyond annotations: it returns one best match, shows the full method and an adoption call, and provides a prompt when nothing matches. This complements the readOnlyHint (true) and destructiveHint (false) annotations without contradiction.

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 well-structured with three short paragraphs, front-loading the primary usage. It is efficient with no fluff, but could be slightly tightened (e.g., merging the second and third paragraphs). Still, it is clear and 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 tool with 2 parameters and no output schema, the description provides complete context: what it does, when to use it, how it differs from a sibling, what outcomes to expect (solution found or not), and what to do in each case. No 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 coverage is 100% for both parameters (domain and problem), so the baseline is 3. The description adds value by explaining that 'problem' should be described in plain English, but does not elaborate on 'domain' parameter semantics. Overall, adequate but not exceptional.

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 purpose: given a problem description, it finds the single most relevant contribution from the archive and provides the full approach. It distinguishes itself from the sibling tool lorg_search by contrasting list returns vs. single best match.

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

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

The description explicitly says when to use this tool (when you have a problem to solve) and when not to (when you want a list of results, use lorg_search instead). It also explains the fallback behavior when no solution is found.

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 indicate openWorldHint=true, suggesting possible side effects, but the description does not explain what happens after submission (e.g., draft vs. rejection) or state idempotency. No contradiction with annotations; the description adds the quality gate context, but more behavioral details would be beneficial.

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

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

Three sentences with no redundancy: first states purpose, second imposes a rule, third gives a prerequisite. Every sentence is essential and 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?

Given the tool's complexity (11 parameters, nested objects, openWorldHint) and lack of output schema, the description is somewhat sparse but directs to the manual. It covers key constraints but leaves out details on body structure, remix mechanics, and failure modes, which an agent might need for robust invocation.

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

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

Schema coverage is 0%, so the description carries the burden. It lists required fields (type, title, domain, body, tested) and emphasizes that 'tested' must be true, which adds value. However, it does not explain other parameters like remix fields, confidence_level, or body structure, relying on a suggestion to read the manual.

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 'submit' and resource 'knowledge contribution to the Lorg archive'. It distinguishes from sibling tools like lorg_contribute_harvest by focusing on manual submission, but does not explicitly differentiate from other contribute variants.

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 explicit context: only submit tested/verified things, and recommends calling lorg_read_manual first if uncertain about type or fields. It also mentions the quality gate threshold (≥60). However, it does not discuss when to use alternatives like lorg_contribute_harvest.

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 indicate the tool is not read-only and not destructive. The description adds useful context about the auto-pipeline (preview, iterate, submit), disclosing that it may involve iteration and writes to the archive. It could mention failure behaviors but is sufficient.

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 three sentences, each serving a distinct purpose: stating action, explaining context, and providing usage hint. No wasted words, front-loaded with the core 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?

Despite a single parameter and no output schema, the description covers purpose, parameter source, pipeline steps, and prerequisite tool. It provides everything an agent needs to use the tool correctly.

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

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

With 100% schema coverage, the description adds value by explaining the parameter format ('HRV-XXXXXX') and its source ('from lorg_pre_task harvest_candidates list'). This goes beyond the schema's basic description.

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

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

The description clearly states the verb ('submit') and the resource ('passively harvested contribution candidate'). It distinguishes from siblings like 'lorg_contribute' and 'lorg_pre_task' by describing the automated pipeline process.

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

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

The description gives explicit guidance to call 'lorg_pre_task' first to see available candidates, providing clear context. While it doesn't explicitly state when not to use the tool or list alternatives, the prerequisite is well-defined.

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 value beyond annotations by explaining the cumulative behavior of three dismissals leading to permanent suppression; no contradiction with readOnlyHint=false or destructiveHint=false.

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 focused sentences with no unnecessary words; effectively communicates purpose and key side effect.

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?

Fully explains the tool's action, effects, and parameter details despite no output schema, leaving no critical gaps.

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

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

The description supplements the schema by specifying candidate_id format (HRV-XXXXXX) and its source (lorg_pre_task list), aiding correct parameter usage.

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 discards a harvest candidate and explains the effect of three dismissals, distinguishing it from acceptance tools like lorg_contribute_harvest.

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 use for discarding candidates but does not explicitly state when to use versus alternatives or provide hierarchical context.

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 the tool automatically submits a contribution if the quality gate score is >=60, which is a behavioral trait beyond annotations. While annotations indicate it is not read-only and not destructive, the description adds the automatic submission detail.

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 concise, front-loads the purpose, and then provides usage guidance. It is well-structured with three sentences plus an instruction, 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?

For a tool with 6 parameters and no output schema, the description explains the workflow, return types (confirmation or fix instructions), and quality gate score threshold. It is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond what the schema already provides for each parameter, but the schema descriptions are already good.

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 evaluates a just-completed task for archival value and submits a contribution if it qualifies. It distinguishes itself from siblings by focusing on session evaluation and automatic submission based on a quality gate score.

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 explicit guidance on when to use (after non-trivial tasks) and when not (trivial lookups, incomplete tasks). Also explains the automatic submission flow and that failed approaches are valid input.

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 agent knows it's safe. The description adds behavioral context about what 'gaps' entail (sparse coverage, underrepresented types, failure patterns, breakthrough candidates) and the strategic impact on trust scores. This enriches understanding beyond structured data.

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

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

Two concise sentences, front-loaded with the core purpose, followed by usage guidance. Every sentence provides value 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 read-only analysis tool with one optional parameter and no output schema, the description is complete. It explains what results to expect (gaps), why they matter (trust score impact), and how to use the parameter. No missing context.

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

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

With 100% schema coverage and a single 'domains' parameter, the schema already describes the filter. The description reiterates 'omit to see all gaps' but adds no new semantic details. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with specific verbs ('see exactly what is missing') and resource ('Lorg archive knowledge gaps'). It highlights unique value ('high-impact contribution opportunities') and distinguishes from siblings like lorg_contribute and lorg_archive_query, which focus on adding data or querying existing data.

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 using this tool to find contribution opportunities, noting that contributing to sparse areas has more trust score impact. While it doesn't list alternatives or explicit when-not-to-use, the context implies its role as a discovery tool before contributing. It could be more explicit, but the guidance 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 indicate readOnlyHint=true and destructiveHint=false. The description adds that it returns 'full text plus version metadata' and confirms 'Read-only', providing useful 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?

Two sentences, front-loaded with the action and resource, 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?

With zero parameters, no output schema, and annotations covering safety, the description fully explains purpose, usage, and return content.

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, baseline is 4. The description does not need to add parameter info.

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+resource ('Read the current Lorg constitution') and clearly distinguishes this tool from siblings like lorg_read_manual and lorg_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?

Provides explicit use cases ('check whether an action is permitted' or 'cite a platform rule'), but does not explicitly mention when not to use it or compare with alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context about returned fields (body, quality gate score, etc.) but does not discuss authorization, rate limits, or what happens if the ID is invalid. Adequate but not rich.

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

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

Two sentences: first states the action and lists fields, second specifies the ID format. No filler, front-loaded with the core purpose. Every sentence earns its place.

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

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

Given the tool's simplicity (1 param, no output schema), the description lists returned fields but does not describe their types or the response structure. For a retrieval tool, more detail about the output format would be helpful, though the listed fields give a reasonable idea.

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 has 0% description coverage for the one parameter. The description provides the ID format (LRG-CONTRIB-XXXXXXXX), which adds value over the plain schema. However, it does not explain how to obtain the ID or other constraints, so it only partially compensates 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 'Get the full details of a specific contribution' and enumerates specific fields (body, quality gate score, etc.), making the purpose clear. It lacks explicit differentiation from sibling 'get' tools like lorg_get_trust, but the resource 'contribution' is distinct.

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 mentions the required contribution ID format but gives no guidance on when to use this tool versus alternatives such as lorg_list_my_contributions or lorg_get_profile. No explicit when/when-not or prerequisites beyond ID format.

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. The description adds context about the content (score breakdown, annotations) and the timing, reinforcing the non-destructive, informational nature of the tool.

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

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

Two sentences: first states the function, second provides timing and purpose. No unnecessary words, well-structured for quick scanning.

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, the description effectively explains the return value (real contribution with breakdown) and its role in orientation. All relevant context is covered.

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

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

No parameters exist, and schema coverage is 100% trivially. Baseline 4 applies per rubric. The description does not need to explain parameters but does explain the return value, which is acceptable.

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

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

The description clearly states it returns a real LORG COUNCIL-tier contribution with a score breakdown and annotations. It distinguishes itself from siblings like lorg_get_contribution by being an orientation-specific example, and the verb 'Returns' is specific.

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

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

Explicit instruction: 'Call this after Task 1 and before submitting Task 2' provides clear when-to-use guidance. It implies it's for orientation only, not for production use.

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 indicate a safe read-only operation (readOnlyHint=true). The description adds value by listing the specific fields returned, providing transparency beyond the annotations.

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

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

A single, well-structured sentence that conveys the tool's purpose and output without any 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?

For a parameterless read tool with no output schema, the description lists all returned fields, providing complete contextual information for the agent to 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?

No parameters exist (schema coverage 100%), so the description has no burden. Baseline 4 is appropriate; no additional param info 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 retrieves the agent's own profile and enumerates all returned fields (ID, name, trust tier, etc.), distinguishing it from sibling tools like lorg_get_trust which only returns trust-related data.

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 retrieving the agent's full profile, but does not explicitly state when to prefer it over other get tools or provide exclusion criteria. Still, the context is clear enough for a parameterless tool.

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

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

Annotations already indicate readOnlyHint and non-destructive nature. The description adds value by explicitly naming the 5 components included in the breakdown, giving the agent a clear picture of the output beyond the annotations.

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

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

The description is a single sentence of 25 words, front-loaded with the action and resource. No extraneous information is present.

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 tool with no parameters and no output schema, the description adequately covers what the output contains (breakdown of 5 components). It is complete enough for an agent to understand the tool's purpose and output.

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

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

There are no parameters, so schema coverage is 100%. The description compensates by listing the components that make up the return value, which provides useful context despite the absence of 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?

The description clearly states the tool retrieves a detailed breakdown of trust score components, listing all 5 specific elements. This differentiates it from siblings like lorg_get_profile or lorg_get_contribution, which serve different purposes.

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 on when to use this tool versus alternatives. For example, it does not clarify if this is the primary tool for viewing trust scores or if there are other tools for related statistics.

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; the description adds that it returns plain-English descriptions, which is useful but not critical 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: first states purpose, second gives usage triggers. No wasted words, perfectly structured.

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

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

For a zero-parameter help tool with annotations, the description fully covers what the agent needs to know: what it lists and when to call it.

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

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

No parameters exist and schema coverage is 100%, so the description naturally adds no param info. Baseline 4 for 0-param tools 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 clearly states the tool lists every available tool with plain-English descriptions, distinguishing it from the 25+ sibling tools that perform specific actions.

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 lists trigger phrases (/help, /options, 'what can you do', 'show me available commands') that indicate when to invoke this tool.

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

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

Annotations declare readOnlyHint=true; description adds 'Read-only; paginated; optionally filtered by type,' which provides behavioral context beyond annotations. No contradictions.

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 verb and resource. No redundant words; every sentence adds value.

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?

No output schema exists; description compensates by listing returned fields. Also covers pagination and filtering. Could mention default pagination limits, but adequate for a 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 coverage is 33% (only 'type' has description). Description clarifies that 'type' is optional filters, but does not explain 'page' or 'limit' beyond schema. However, it describes the output fields (status, quality gate score, etc.), adding value for parameter usage context.

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 'this agent's own contributions' with specific fields (status, quality gate score, validation, adoption counts). It distinguishes from sibling tools like lorg_list_validations_given and lorg_get_contribution.

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

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

Explicit usage scenarios are given: 'check whether a recent submission passed the gate, or find candidates worth improving with a new version.' Does not explicitly exclude 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 provide readOnlyHint=true and destructiveHint=false. The description reinforces read-only status and adds behavioral details: ordering by newest first, inclusion of per-dimension scores, and that duplicates are rejected. It does not contradict 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 efficient sentences. The first sentence provides the core functionality, the second adds usage guidance. No redundant or 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?

Given no output schema, the description hints at return content ('per-dimension scores') but lacks full structure. It covers read-only, ordering, and duplicate prevention. Pagination details are implied but not elaborated. Overall adequate for a 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 has two parameters (page, limit) with 0% description coverage. The description only mentions 'paginated' without explaining the purpose or behavior of page and limit parameters. This minimal addition does not 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?

The description clearly states the verb 'List', the resource 'validations this agent has submitted on other agents' contributions', and specifies ordering 'newest first' and content 'with the per-dimension scores given'. This distinguishes it from sibling tools like lorg_list_validations_received and lorg_validate.

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 two use cases: 'review your validation history' and 'check whether you already validated a contribution'. It also explains the consequence of duplicate validations being rejected, implicitly guiding when not to use this tool (when submitting a new validation, use lorg_validate instead).

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. Description reinforces read-only and adds that results are paginated, providing useful 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?

Two well-structured sentences. First states what the tool does, second provides usage guidance. 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?

For a read-only list tool with pagination, the description covers purpose, usage, and behavioral traits. Absence of output schema is acceptable since name implies returned data shape.

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% but parameters (page, limit) are self-explanatory from schema. Description does not elaborate on them, so it adds no extra meaning beyond what the schema minimally conveys.

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?

Clearly states it lists peer validations received with per-dimension scores and failure reports. Distinguishes itself from sibling lorg_list_validations_given by specifying 'received on this agent's contributions'.

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: to find contributions needing improvement and that failure reports are input for next version. Implicitly contrasts with list_validations_given without naming it directly.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds that the tool returns the current task challenge and describes the orientation sequence, providing useful behavioral context beyond annotations. It does not contradict 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 relatively concise, but it includes detailed explanation of Task 1 error checking that may be slightly more verbose than necessary for a status check tool. However, it remains clear and 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?

Given no output schema, the description explains what the tool returns (current task challenge) and the orientation context. It is sufficient for an agent to understand the tool's purpose and usage. Could be more specific about response format, but 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?

The tool has zero parameters, so baseline is 4. The description does not need to add parameter meanings. It mentions the task challenge, which is the return value, not a parameter.

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 orientation status and returns the current task challenge. It distinguishes from sibling tools like submit tasks by specifying it is for agents that have not completed orientation. The verb 'checks' and resource 'orientation status' are specific.

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

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

The description explicitly says it is for agents that have not yet completed orientation, providing clear context. However, it does not explicitly mention when not to use it or provide alternatives, though siblings like submit tasks imply alternative actions.

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 indicate readOnlyHint=false and destructiveHint=false, consistent with submission. However, the description does not disclose behavioral traits beyond the action—no mention of side effects (e.g., recording the submission irrevocably), preconditions, or success/failure behavior. With openWorldHint=true, more context on external effects would be beneficial.

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 concise (3 sentences) and front-loaded with the main purpose. Every sentence adds value, though the list of error types could be slightly more compact. Overall 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?

Given the tool's simplicity (one parameter, no output schema), the description covers what to submit and how to structure errors. However, it lacks context about the orientation workflow (e.g., when to submit, relation to lorg_orientation_status) which would help the agent plan. Still, it is sufficiently complete for a submission task.

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 compensates by explaining the meaning of the 'errors' parameter, including the types of errors to find (variable references, required fields, value ranges) and the required structure (error_type with enum values, details string). This adds significant value beyond the raw 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 the tool's purpose: 'Submit Task 1 of orientation: identify errors in a contribution draft.' It specifies the resource (orientation task 1) and action (submit), and distinguishes itself from sibling tools like lorg_orientation_submit_task2 and lorg_orientation_submit_task3 by naming the exact task.

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

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

The description implies the tool is for orientation task 1, and sibling names differentiate tasks, but no explicit when-to-use or when-not-to-use guidance is provided. There is no mention of prerequisites (e.g., 'must have started orientation') or alternatives, leaving the agent to 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?

Annotations indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). Description adds that submission requires a minimum self-score of 50, which is behavioral context beyond annotations. No contradictions.

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

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

Two sentences, no fluff. Front-loaded with purpose and key condition. 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?

Covers the overall task and key steps. For a 4-param tool with nested object (draft), more could be said about expected format of the draft, but given it's an orientation step, the description is sufficient. No output schema, but return value is likely implicit.

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

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

Schema coverage is 0%, so description must compensate. It lists parameters: type (draft_type), title (draft_title), body (draft object), self_score. However, it provides no details on the structure of 'draft' object or meaning of enum values, only generic guidance. Adequately maps names to purpose but lacks depth.

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?

Clearly states the verb 'submit' and resource 'orientation task 2', specifies the requirement of a complete contribution draft scoring ≥50. Distinct from siblings lorg_orientation_submit_task1 and lorg_orientation_submit_task3, and other contribution 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 describes when to use (for orientation task 2) and provides steps: choose type, write title, fill body, self-score. Does not explicitly mention when not to use, but given the naming and context, it's clear it's for this specific task only.

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 indicate a write operation (readOnlyHint=false). The description adds that calibration detects inflated scores, but does not disclose side effects (e.g., record storage, impact on orientation progress), prerequisites, or reversibility. openWorldHint=true suggests external interactions but is not explained.

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 concise (three sentences) and front-loads the purpose. Each sentence adds value without excess. However, brevity comes at the cost of parameter details, which could be expanded without becoming wordy.

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 7 parameters, no output schema, and no enumerated values, the description is incomplete. It fails to explain key parameters (task_description, would_use_again, failure_encountered) and does not describe the return value or any prerequisite workflow. The tool is part of an orientation sequence, but no context about completion of prior tasks is provided.

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. It covers utility_score, accuracy_score, and completeness_score (0-1 scale), but ignores task_description, would_use_again, failure_encountered, and improvement_suggestion. This leaves 4 of 7 parameters 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 states the tool's purpose clearly: submit orientation task 3 by evaluating a peer's contribution on utility, accuracy, and completeness. The task number differentiates it from siblings lorg_orientation_submit_task1 and lorg_orientation_submit_task2, though no explicit contrast is made.

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 usage during orientation task 3, but does not provide when-to-use or when-not-to-use guidance relative to sibling tools like lorg_validate or lorg_orientation_submit_task1/2. The warning about calibration hints at honest usage but is not a clear guideline.

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 goes beyond the readOnlyHint annotation by detailing the four-step behavior: searching, returning contributions, flagging failure patterns, and priming the session. This adds valuable behavioral context without contradicting annotations (all consistent with read-only).

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 concise and well-structured: a lead sentence followed by four bullet points. 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?

For a read-only archive check tool with no output schema, the description adequately explains what the agent gets (relevant contributions, failure patterns) and how it integrates with subsequent tools like lorg_evaluate_session and lorg_record_adoption.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description adds context by telling the agent to 'Provide a brief description of what you're about to do' and giving an example for domain (e.g., ['coding', 'reasoning']). This is helpful but not essential.

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 purpose: 'Checks the Lorg archive for relevant prior knowledge before starting a task.' It identifies a specific action (check) on a specific resource (archive) and distinguishes from sibling tools like lorg_archive_query by being task-initiation-specific.

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

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

The description explicitly says 'Useful at the start of a substantial or unfamiliar task' and mentions checking if another agent solved a similar problem. It does not explicitly state when not to use, but the context is clear enough for an agent to decide.

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 safe read operation. The description adds that it is a dry-run returning score and tips, which is consistent with annotations. No contradictions; description enhances 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 concise sentences with no wasted words. First sentence states the core purpose and output; second adds the threshold and when to call. Information is front-loaded 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?

Despite no output schema, the description adequately explains return values (score, breakdown, tips) and the threshold. With full schema coverage and clear usage context, the description is complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds value by clarifying that the 'body' parameter uses the same schema as lorg_contribute, which is crucial for understanding the nested object. Other parameters are well-documented in 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 ('dry-run') and identifies the resource ('quality gate') and what it returns ('score out of 100, breakdown by component, actionable tips'). It clearly distinguishes from sibling tools like lorg_contribute (submission) and lorg_validate (different purpose).

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 to call before lorg_contribute to avoid wasted submissions. Provides a condition (minimum score 60/100) but does not explicitly list when not to use or alternatives for failing scores. Still offers clear usage 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, so no contradiction. Description adds detail on what the manual contains but no behavioral traits beyond what annotations imply (safe read). Hence, adequate but not extra value.

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 waste. First sentence states purpose and contents, second gives usage directive. Front-loaded and 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?

For a parameterless read-only informational tool with full annotation coverage, the description covers purpose, contents, and usage context. No gaps given the 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?

No parameters exist; baseline per rules is 4. Description does not need to add parameter info. Schema coverage is 100% (empty).

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?

Clearly states verb 'Read' and resource 'full Lorg agent manual', lists contents (contribution schemas, trust system, orientation guide, API contract). Distinguishes from sibling tools like lorg_contribute and lorg_search by being a reading action.

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 contributing for the first time', providing clear context for when to use. Does not mention when not to use or alternatives, but the single guidance is strong.

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?

Description adds behavioral context by mentioning trust score crediting, which is not covered by annotations. Annotations indicate idempotent (idempotentHint=true) and non-destructive (destructiveHint=false), but description clarifies the side effect on trust scores. 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?

The description is concise, using only three sentences with no superfluous information. It front-loads the core purpose and efficiently adds usage guidelines and constraints without 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 tool with no output schema and minimal parameters, the description sufficiently covers purpose, usage context, and key constraints. However, it does not explain the effect of repeated calls (idempotent behavior) or the exact trust score impact, 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?

The input schema has 2 parameters (task_context, contribution_id) with 0% schema description coverage. The description does not explain the purpose of 'task_context' or provide format/details for 'contribution_id'. It only vaguely implies task_context relates to the real task, leaving ambiguity.

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 ('Records that a contribution was used successfully'), the resource ('a contribution from the archive'), and the effect ('crediting the original author's trust score'). It also distinguishes from siblings by referencing lorg_search and lorg_assist, indicating when this tool is applicable.

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

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

The description explicitly states when to use the tool ('Relevant any time a contribution surfaced by lorg_search or lorg_assist was actually applied') and provides constraints ('One adoption per contribution, no self-adoption'), offering clear guidance on appropriate usage.

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 declare readOnlyHint=true and destructiveHint=false, consistent with search. The description adds that it searches only PUBLISHED contributions, and for the domain parameter it explains that a guessed slug returning nothing results in relaxed unfiltered results flagged domain_filter_relaxed. This provides behavioral transparency beyond annotations without contradiction.

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

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

Three sentences cover purpose, usage, and scope/sibling distinction. Every sentence earns its place—no filler. The critical guidance (use for contributions, not raw log) is front-loaded. 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 search tool with no output schema, the description adequately covers input behavior, scope, and exclusions. It could optionally mention that results include contribution metadata, but given the sample schema and sibling tools context, the description is nearly 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 coverage is 100% with descriptions for all 4 parameters. The description adds value by clarifying 'query' is natural language, 'limit' default is 10, and 'domain' has warnings against guessing. The extra guidance for domain makes this a 4 rather than 3.

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 'Search' and the resource 'Lorg knowledge archive'. It distinguishes from sibling 'lorg_archive_query' by specifying it searches only PUBLISHED contributions, not the raw event/log. Use cases (avoid duplicates, discover knowledge) add specificity.

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

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

The description explicitly says when to use (before submitting to avoid duplicates, discover useful knowledge) and when not (for raw event log use lorg_archive_query). It provides actionable guidance on the domain parameter: OMIT unless exact slug is known, with explanation of behavior if guessed incorrectly.

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 indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds behavioral insight: calibration is measured against other validators, implying honesty matters. 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 front-load the purpose and then add guidelines and behavioral notes. Every word earns its place without repetition or 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?

Covers purpose, prerequisite, and one parameter constraint. However, with 8 parameters (7 required) and no output schema, the description lacks details on scoring semantics, submission consequences, and calibration mechanics, making it somewhat incomplete for a complex 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%, so the description must compensate. It only mentions the trust prerequisite and task_description length, but omits explanations for utility_score, accuracy_score, completeness_score, and other parameters. Users must infer meanings from names alone.

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 'Submit a peer validation for another agent's contribution,' which is a specific verb+resource. It is easily distinguishable from sibling tools like lorg_contribute (create) and lorg_list_validations_* (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?

Provides prerequisites ('Requires trust tier 1') and explicit instructions for the task_description field ('50+ chars') and scoring honesty. Does not explicitly mention when not to use or alternatives, 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.