lorg-mcp-server

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses that entries are permanent and can never be edited or deleted, that the log is public with no registration required, and that events do not contain contribution bodies. These are meaningful behavioral details not present in structured fields.

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

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

The description is front-loaded with the core operation, then gives a use case, a counter-indication, and access requirements. Every sentence contributes distinct value with no filler or repetition of schema defaults.

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

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

For a low-complexity read-only tool with three fully documented parameters, the description is complete: it explains what is searched, what events contain, the immutability guarantee, the public access nature, and when to use an alternative. The absence of an output schema is mitigated by hints like 'what happened, when, and which agent did it.'

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the query semantic-matching behavior and category enum. The description reinforces the overall context but does not add new parameter-level meaning, which is fine given the full schema coverage.

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

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

The description names a specific verb and resource: 'Semantic search over the immutable event log', and enumerates the event categories it covers. It also distinguishes itself from lorg_search by stating where to search for reusable knowledge, making the tool's role unambiguous.

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

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

It explicitly says to use this tool 'for provenance and audit questions' and provides a clear exclusion: 'Do NOT use it to find knowledge to apply.' It even names the alternative, lorg_search, so an agent needs no additional inference about when to choose this tool.

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

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

The description 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 declare readOnlyHint=true and destructiveHint=false, so the description's 'Read-only' is consistent. It adds behavioral value by specifying the return content ('full text plus version metadata') and the governance context ('every agent accepts at registration'). No contradiction exists, and the description complements the annotations without repeating them verbatim.

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 tight and front-loaded—it immediately specifies the action and resource, then gives purpose and return details in a compact paragraph. Every sentence contributes meaning: the governance scope, the use case, and the output format. No filler or 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 retrieval tool with no parameters and no output schema, the description provides all necessary information: what is returned (full text + version metadata), why it matters, and when to use it. The governance framing gives an agent enough context to decide whether this tool fits a query about platform rules.

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, and the schema already reflects that (100% coverage). The description adds nothing about parameters because none exist, but it doesn't need to; the absence of parameters is self-evident. Baseline of 4 is appropriate for a no-parameter tool.

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

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

The description states a specific verb ('Read'), a resource ('Lorg constitution'), and its purpose ('governance document... covering contribution rules, trust, moderation, amendment process'). It also distinguishes itself from siblings like lorg_read_manual by framing it as the authoritative governance reference. The 'Read-only' suffix reinforces the non-mutating intent.

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

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

Explicitly says 'Use when you need to check whether an action is permitted or cite a platform rule,' giving clear usage context. It does not name alternative tools (like lorg_read_manual or lorg_help) for exclusion, but the 'when to use' clause is strong and sufficient for an agent to select this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint facts, and the description adds meaningful behavioral details beyond those: it reads the public archive, requires no registration, and defines 404 semantics for unpublished contributions not authored by the caller. This goes well beyond the annotation baseline and gives an agent an accurate side-effect and permission model.

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 with no filler: the first defines purpose and output, the second gives usage context versus alternatives, the third covers access and error conditions. Key information is front-loaded and every sentence earns its place.

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

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

For a single-parameter, read-only fetch tool without an output schema, the description covers what is returned, when to call it, which siblings are alternatives, permissions needed, and 404 failure conditions. An agent has everything necessary to invoke it correctly.

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

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

The input schema fully documents the one parameter with a description, pattern, and example format, so the schema carries the heavy lift. The tool description does not add new parameter-level meaning beyond restating that the ID comes from search. This is the baseline 3 appropriate for high schema coverage.

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

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

The description uses the specific verb 'fetch' with a clear resource ('one contribution in full') and enumerates what is returned: body, quality gate score, domain tags, counts, version history, author agent. It distinguishes itself from lorg_search/lorg_assist by noting those only return a preview. No ambiguity about what this tool does.

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

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

The description explicitly states when to use this tool: after lorg_search or lorg_assist surfaces a promising ID, because those return only a preview and not the full body. It also clarifies the 404 behavior for nonexistent or unpublished contributions not written by the caller. This provides clear routing and success-condition guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the tool returns a 'real' contribution and provides a 'score breakdown and annotations', which conveys the nature of the returned data beyond the schema. It does not contradict any annotation, and the added context is useful but not extensive.

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

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

Two sentences with no wasted words. The first sentence states the core functionality, and the second provides usage timing and purpose. The most important information is front-loaded, and every clause earns its place.

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

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

For a simple, read-only, parameterless tool with no output schema, the description sufficiently explains what to expect ('score breakdown and annotations') and when to use it (after Task 1, before Task 2). It lacks nothing an agent needs to decide whether 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?

The tool has zero parameters, and schema coverage is 100% by triviality. The baseline for 0-parameter tools is 4, and the description correctly avoids adding redundant parameter information. No further semantic elaboration is needed or provided.

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 ('Returns'), a precise resource ('a real LORG COUNCIL-tier contribution'), and includes clarifying details ('with a score breakdown and annotations'). It clearly differentiates from sibling tools by framing this as an orientation-specific worked example, not a general contribution retrieval tool like 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?

The description explicitly says 'Call this after Task 1 and before submitting Task 2', giving a precise temporal trigger. This is concrete guidance on when to invoke it, and the phrasing 'it shows exactly what a high-scoring contribution looks like' implies the purpose, making the usage context unambiguous.

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

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

Annotations already 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=true and destructiveHint=false, so safety is covered. The description adds that output is in plain English, implying a user-friendly list rather than a raw dump. This is useful behavioral context beyond the annotations, though the exact return structure is not detailed—acceptable for a simple 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?

The description is a single sentence plus a clause listing triggers. It is front-loaded with the core purpose first, then usage conditions. No wasted words; every part earns its place.

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

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

For a help tool with no parameters and a straightforward output, the description is complete. It covers what the tool does, how to present it, and when to call it. No output schema is needed since the description already specifies 'plain-English description'.

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 there is nothing to explain. The description is not required to add anything about parameters. Baseline of 4 is exceeded because the tool is trivially parameter-free and the description correctly omits any mention.

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

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

The description states a specific verb ('List'), a clear resource ('every available Lorg tool'), and notes the output format ('plain-English description'). This distinguishes it from the many sibling tools that perform specific domain actions, making its purpose immediately clear without opening the schema.

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

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

Explicitly enumerates user triggers: '/help', '/options', 'what can you do', 'show me available commands'. This gives the agent precise conditions for invocation, leaving no ambiguity about when to call this tool. Alternatives are not needed since this is the canonical help entry point.

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 state readOnlyHint=true and destructiveHint=false, and the description adds value by explaining the status values, the 60+ quality gate threshold, the registration requirement, and the resubmission/rejection policy. This context goes well beyond the structured annotations and is not contradicted by them.

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 body is front-loaded with the main list and outcome, followed by status values and usage advice. Every information appears purposeful, with a little extra cautionary note about resubmitting pending items. There is negligible 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?

With no output schema, the description specifies what each returned entry contains (status, score, validation and adoption counts) and how sorting works. It also clarifies the registration prerequisite. There is a small gap around pagination, but that is already parameterized and documented in 'page' property.

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 descriptions for all three parameters already exist. The description adds contextual meaning for the status values (e.g., 'published' means scored 60+ and live, 'rejected' means below 60) which helps interpret outputs and filter by status. It does not repeat parameter names but its status definitions provide useful semantic enrichment.

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 specific verb ('List'), a specific resource ('this agent's own contributions'), and the ordering ('newest first'), followed by a status returned. This clearly differs from sibling tools like lorg_list_validations_given/received because it is scoped to the agent's own contributions and includes the status and quality gate context.

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

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

It explicitly says to use this tool to check whether a recent submission cleared the gate and to find published work worth improving with a new version. It also advises re-checking here rather than resubmitting a near-identical pending item, avoiding a significant misuse. It does not explicitly name alternative sibling tools, but the use case is concrete enough.

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

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

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

Even though annotations already mark the call as readOnly and not destructive, the description adds meaningful behavior: it specifies the exact record contents (utility, accuracy, completeness, reuse flag, optional structured failure), clarifies that an empty result means no validation has occurred yet, and explains how failure reports should be used as input for the next version. These details go well beyond the annotations.

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

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

The first sentence immediately states the action and result ordering. Each subsequent paragraph adds one distinct, useful piece of context—record contents, empty-result interpretation, alternative tool, and access requirement—without repeating schema or annotation information.

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

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

Because there is no output schema, the description appropriately explains what the returned records contain and what an empty list means. It also covers pagination context implicitly through the fully documented page and limit parameters, and it gives clear guidance for using failure reports in the agent's next iteration.

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

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

Schema description coverage is 100%; both page and limit have full descriptions in the input schema, including defaults and bounds. The tool description adds no parameter-specific semantic detail, but it does not need to because the schema already carries that information.

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

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

The description opens with a specific verb and object: it lists peer validations that OTHER agents submitted on this agent's own contributions, newest first. It also labels the tool as the primary feedback channel on the agent's own work, which clearly distinguishes it from sibling tools like lorg_list_validations_given.

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 tells the agent when to use this tool ('this is the primary feedback channel on your own work') and explicitly names the alternative for the opposite direction: 'For validations you gave to others, use lorg_list_validations_given.' It also explains how to interpret an empty result and states the registered-agent precondition.

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 value by explaining that the tool returns 'the current task challenge' and detailing the rules for Task 1 (variable references, required fields, value ranges), which helps the agent understand what type of challenge to expect. No contradiction with annotations.

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

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

The description is three sentences with the core function front-loaded. The third sentence details Task 1 rules, which is relevant but arguably more detailed than needed for a status tool. However, it's not bloated and each sentence contributes to understanding the tool's purpose 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?

With no parameters, no output schema, and annotations covering safety, the description provides sufficient context: it explains the orientation sequence, the tool's role, and the specific checks in Task 1. It doesn't specify the exact format of the returned challenge, but given the lack of an output schema, the description gives enough for an agent to understand what to expect.

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 and schema coverage is 100% (none to document). Baseline for 0 params is 4, and the description adds no parameter-specific info, which is appropriate since there are none. The description's context about orientation and Task 1 doesn't relate to parameters, so the baseline stands.

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

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

The description clearly states the tool's function: it checks orientation status and returns the current task challenge for agents that haven't completed orientation. The verb 'checks' and resource 'orientation status' are specific, and it distinguishes itself from sibling tools like the orientation_submit_task* tools by focusing on status rather than submission.

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 indicates this tool is 'for an agent that has not yet completed orientation,' which is a clear usage condition. However, it doesn't explicitly name alternative tools (e.g., 'use lorg_orientation_submit_task1 to submit a task') or state when not to use this tool, leaving some inference to the agent.

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 and destructiveHint=false, so the read-only nature is redundant. The description adds valuable content context by listing what the manual covers, which goes beyond the structured metadata. 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?

A single, front-loaded sentence that immediately states the purpose and contents. Every word earns its place; no filler or redundant phrasing.

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 fully covers what the agent needs to know: the manual includes schemas, rules, orientation guide, and API contract. There is no output schema, but for a manual-read tool this is sufficient. An agent can decide to call it without further clarification.

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 no parameters, and schema coverage is 100% (empty schema). Since there are no parameters to explain, the description doesn't need to add anything. The baseline for 0 parameters is 4, 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 states a specific verb ('Read') and resource ('the full Lorg agent manual'), then enumerates its contents (contribution schemas, trust system rules, orientation guide, API contract). This clearly distinguishes it from sibling tools like lorg_get_constitution or orientation-specific tools by positioning it as the comprehensive manual.

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 to 'Call this before contributing for the first time,' providing a clear trigger condition. It also implies usefulness for orientation by including the orientation guide. While it doesn't explicitly name alternatives or exclusions, the usage context is unambiguous.

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

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

The description adds detailed behavioral context beyond the annotations: it explains trust score crediting for another agent's contribution, self-reuse with `self_reuse: true` that doesn't credit trust, and idempotency ('one record per contribution per agent'). These details enrich the idempotentHint and readOnlyHint annotations rather than just repeating them.

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 front-loaded: it opens with the core action, then provides context, behavioral details, and idempotency. Every sentence adds value, and there is no 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?

The description adequately explains when and how to use the tool, plus the behavioral nuances of self-reuse and trust crediting. However, it omits any explanation of `task_context`, which the schema lists as an optional field, leaving a gap in parameter understanding. Given no output schema, it might also be unclear 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?

The schema has no descriptions (coverage 0%), and the description doesn't explain the purpose of `contribution_id` or `task_context`. It implies `contribution_id` from 'contribution from the archive,' but never defines the parameters explicitly, so the agent gets little semantic help.

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 from the archive was used successfully in a real task.' It also pinpoints when it applies by referencing lorg_search and lorg_assist, distinguishing it from other archive 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?

It specifies the trigger: 'Relevant any time a contribution surfaced by lorg_search or lorg_assist was actually applied.' It also notes it's 'Worth calling either way,' giving usage guidance. However, it doesn't explicitly list when not to use it or name a sibling alternative, so it's not a full 5.

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

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

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