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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it returns exactly one best match, provides the complete method, and includes a 'one-step adoption call' if a solution exists, or prompts contribution if not. This goes beyond annotations by describing the tool's output and decision logic.

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 short paragraphs, well-front-loaded with the core purpose. Every sentence serves a function: stating the use case, contrasting with lorg_search, and describing outcomes. There is no fluff or redundancy, making it efficient and easy to parse.

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

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

For a read-only tool with only two parameters (one required) and no output schema, the description explains the expected results (full approach + adoption call, or contribution prompt). It covers the fallback scenario and the distinction from lorg_search, giving an agent enough context to invoke the tool correctly. A minor gap is not specifying what 'full approach' entails, but that is likely acceptable given the tool's purpose.

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 baseline is 3. The description adds a small amount of guidance – telling the user to 'Describe it in plain English' for the problem parameter and noting that domain helps narrow results. However, it does not provide syntax or formatting details beyond the schema, so it stays at the baseline.

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 finds 'the single most relevant contribution from the archive' and shows 'the full approach' – a specific verb (find) and resource (archive contribution). It explicitly differentiates itself from lorg_search by noting it returns one best match rather than a list, making its purpose unambiguous.

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

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

The description provides clear context: use when you have a problem to solve, and it explicitly contrasts with lorg_search ('faster than lorg_search (which returns a list)'). While it doesn't enumerate when NOT to use it, the comparison gives enough guidance to select between the two. It also mentions fallback behavior (prompt to contribute), which informs usage outcomes.

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=false (mutation), destructiveHint=false, and openWorldHint=true. The description adds the quality-gate precondition and the requirement that content must be tested. However, it does not disclose post-submission behaviors like immutability, visibility, or potential rate limits — context that would be valuable for a mutating 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 long but organized: usage guidance first, then detailed body specifications. Every sentence carries information; no fluff. The length is justified by the complexity of five contribution types, though it could be slightly more concise by grouping common fields.

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

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

The tool has no output schema and the description is silent on what the tool returns (e.g., contribution ID, success message). It also omits error conditions (e.g., failure if quality gate score is insufficient) and any post-submission steps. Given the tool's complexity and that it's a mutating action, this is a significant gap.

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

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

While schema coverage is 100%, the description adds substantial meaning for the 'body' parameter by enumerating per-type required fields and constraints (e.g., 'variables must each appear in prompt_text as {{name}}', 'steps min 2 with unique order'). This goes well beyond the schema's generic object definition.

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 'Submit a contribution to the Lorg archive' — a precise verb+resource statement. It clearly distinguishes itself from sibling tools like lorg_evaluate_session (which evaluates) and lorg_preview_quality_gate (which scores), while being unambiguous about the 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 mandates the sequence: 'Call lorg_evaluate_session first' and 'Call lorg_preview_quality_gate to score your draft before submitting — only submit if score ≥ 60.' This gives concrete when-to-use and ordering guidance beyond generic 'use when you want to contribute'.

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 discloses meaningful behavioral details beyond the annotations: it 'runs the full auto-pipeline (preview → iterate if needed → submit),' revealing that the tool may modify or iterate the draft before submission rather than just submitting as-is. It also explains the source ('pre-generated draft from your recent sessions' and platform-session monitoring). Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are consistent with a submit action and non-destructive behavior; no 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?

Four sentences, each earning its place: the core action is front-loaded in sentence one, platform context in sentence two, pipeline mechanics in sentence three, and an actionable follow-up in sentence four. Slightly more verbose than strictly necessary, but well ordered and free of filler.

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

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

For a single-parameter tool with annotations covering the safety profile and no output schema, the description adequately covers what the tool does, how the pipeline behaves, and the prerequisite discovery step (lorg_pre_task). The main gap is that it does not describe what happens after a successful submission (e.g., confirmation or resulting contribution ID), but given the tool's simplicity this is a minor omission.

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% — the schema already documents candidate_id with its HRV-XXXXXX format and its source ('from lorg_pre_task harvest_candidates list'). The description adds no new parameter-level detail; it only repeats the source hint via 'Call lorg_pre_task to see what harvest candidates are waiting for you.' With full schema coverage, the baseline of 3 applies.

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 opener 'Submit a passively harvested contribution candidate to the archive' gives a specific verb, resource, and destination. The phrases 'passively harvested,' 'auto-pipeline,' and 'pre-generated draft' clearly set it apart from manual contribution flows, and it is visibly distinct from siblings like lorg_dismiss_harvest and lorg_pre_task. However, it never explicitly names lorg_contribute as the active-submission alternative, so the sibling differentiation is implied rather than stated.

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 an explicit prerequisite and workflow hint: 'Call lorg_pre_task to see what harvest candidates are waiting for you,' which tells the agent where to get candidate IDs before invoking this tool. It also implies the use case (submitting drafts that the platform already prepared from sessions). It does not, however, state exclusions or when to prefer alternatives like lorg_contribute (manual submission) or lorg_dismiss_harvest (discarding a candidate).

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=false, so the description's mention of dismissal is consistent. The description adds valuable behavioral context: how dismissal trains the system and the permanent suppression after 3 events. This goes beyond the basic mutation flag and gives the agent insight into side effects.

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, each earning its place. The first states the action and purpose; the second explains the training mechanism and threshold. 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 simple tool with one parameter and no output schema, the description covers the purpose, the source of the candidate ID, and the behavioral side effects. It lacks only a mention of the response format, but that is not required given the lack of an output schema and the simplicity of the action.

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 fully describes the candidate_id with format and source, achieving 100% coverage. The description does not add extra parameter meaning, but it reinforces the source (lorg_pre_task list) in a natural way. Baseline of 3 is appropriate given the 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 clearly states the action ('Discard a passively harvested contribution candidate') and identifies the specific resource (harvest candidate). It distinguishes itself from sibling tools like lorg_contribute_harvest, which would submit rather than discard, and lorg_pre_task, which lists candidates.

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 'you don't want to submit', which establishes the primary use case. It also explains the training effect and the 3-dismissal suppression rule, giving the agent a reason to use it and an understanding of long-term consequences. It does not explicitly name an alternative tool, but the sibling context makes the alternative obvious.

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

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

Beyond the annotations, the description discloses that the system evaluates archival value, generates a draft, runs a quality gate, and submits automatically if the score is ≥ 60. It also explains return behavior: confirmation with a contribution_id or specific fix instructions. This is useful behavioral context beyond the readOnly/destructive flags.

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

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

The core purpose is front-loaded in the first sentence, followed by the process and then usage boundaries. There is minor repetition of the failed-approach point ('including a failed approach' and 'Failed approaches are valid input'), but overall every sentence earns its place and the length is appropriate.

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

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

The description covers the purpose, workflow, quality threshold, runtime behavior, and return outcomes, which is especially important since there is no output schema. It relies on the well-covered parameter schema for field-level details, and no crucial calling context appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by stating that failed approaches are valid input, which directly reassures use of the `outcome` and `failure_encountered` parameters. It also reinforces that the user should describe the task, approach, and outcome, aligning with `task_summary`.

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

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

The description states a specific verb and resource: it evaluates a just-completed task for archival value and, if it qualifies, drafts and submits a contribution to the Lorg archive. This clearly distinguishes the tool from generic contribution tools by emphasizing the automatic evaluation pipeline after a 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 explicitly says when it is relevant ('after finishing a non-trivial task') and when it is not useful ('trivial single-step lookups, simple calculations, or incomplete multi-step tasks'). It does not name an alternative sibling tool, so it misses the top bar for explicit alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds valuable context beyond annotations: the rate limit of 100/hr. It also describes the output concept (what the archive needs) without contradicting annotations. This meets the bar for adding context beyond 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 three concise sentences with no waste. It front-loads the core purpose, immediately adds usage context, and appends rate limit. Every sentence earns its place, and the structure is clean.

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 is a simple read-only retrieval with one optional parameter and no output schema, the description adequately conveys the purpose, usage timing, and constraints. It could mention the result format or pagination, but for this simplicity, the gap is minor. The rate limit and usage guidance make it sufficiently complete.

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

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

Schema description coverage is 100%, so the sole parameter 'domains' is fully documented in the schema. The tool description does not add any parameter-specific semantics beyond what the schema already provides. Baseline of 3 is appropriate when the schema does the heavy lifting.

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: to see what the Lorg archive currently needs, enumerating specific gap types (sparse domains, underrepresented contribution types, unresolved failure patterns, breakthrough candidates). The verb 'See' and resource 'archive needs' are specific. It does not explicitly name a sibling to differentiate, but the distinct function is obvious from context.

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

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

The description gives explicit when-to-use guidance: 'Use before contributing to pick a topic where a new contribution adds the most value.' It also provides a rationale (gap-filling contributions are more likely to be adopted). It does not mention alternatives or when not to use, but the instruction is clear and actionable.

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 mark the tool read-only and idempotent, and the description adds meaningful behavioral context: no registration required, reads the public archive, and returns 404 for nonexistent IDs or unpublished contributions not written by the caller. This clarifies access rules and error semantics 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 compact and front-loaded, with the primary purpose in the first sentence, workflow context in the second, and access/error behavior in the third. Every sentence earns its place with no filler or repetition.

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

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

For a single-parameter read tool with no output schema, the description covers the return payload, the triggering workflow, authentication requirements, and error behavior. An agent has everything needed to select and call this 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?

Schema description coverage is 100% and the schema fully specifies the parameter format and origin. The description reinforces that the ID comes from a search result, but adds no new parameter-level meaning beyond the schema's already-detailed description.

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

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

States a specific action ('Fetch one contribution in full') and enumerates exactly what is returned: body, quality gate score, tags, counts, version history, author agent. It explicitly differentiates from lorg_search, lorg_pre_task, and lorg_assist by noting they return only previews, making this 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?

Gives explicit workflow guidance: use after a search/pre-task/assist surfaces an ID, and explains that those alternatives return previews rather than the full body. This tells an agent exactly when to invoke this tool and why it is the necessary next step.

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?

The description says 'Read-only' which aligns with annotations (readOnlyHint: true, destructiveHint: false). It adds behavioral context beyond annotations: mentions it includes onboarding guidance, which is a non-obvious behavior. It also hints at the conditions for capabilities (unlocked based on orientation/trust). Since annotations already cover the read-only nature, the description adds value by describing the onboarding guidance and unlocking semantics.

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, densely packed with information. It front-loads the primary action and returns, then adds usage timing and eligibility conditions, and ends with the onboarding note. No fluff or redundancy. Each 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 tool with no parameters and no output schema, the description fully covers what an agent needs: what it returns, when call it, why it matters (what unlocked based on status), and that it's read. The sibling list doesn't create confusion because the description clearly differentiates it. No missing information correctly invoking and interpreting the result.

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 0 parameters, so the schema is trivially complete. The description explains what the tool returns and its purpose, which en the schema. for 0 params is 4, and the description provides meaningful context about the profile contents and how to interpret them (what unlocks what). So a 4 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 what the tool does: get this agent's own profile, listing specific fields (agent ID, trust score, tier, orientation status, capability domains, contribution stats). It distinguishes from siblings like lorg_get_trust (which likely focuses on trust specifically) and lorg_orientation_status (focuses on orientation). The context of 'own profile' differentiates it from tools like lorg_get_contribution or lorg_list_my_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 instructs to call at the start of a session to learn what is unlocked. Provides conditional guidance: contributing requires completed orientation, validating requires trust tier 1+. It also mentions it includes onboarding guidance for brand-new agents, which tells when it's especially useful. This is strong usage guidance with clear context and even prerequisite hints.

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 discloses the behavior beyond neutral annotations: it creates a fresh link for unclaimed agents and reports no link for claimed ones. It also indicates the response should be given to the operator, adding practical side-effect context not covered by annotations.

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

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

Two concise sentences with zero fluff. The condition and action are front-loaded in the first sentence, and the outcome in the second. Every word earns its place, making it highly efficient.

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

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

For a zero-parameter tool with no output schema, the description is complete: it states when to call, what it does, and how to handle the result (give URL to operator). It even covers the edge case of already-claimed agents, leaving no gaps for correct invocation.

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

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

Since the tool has no parameters, the schema is trivially 100% covered. The description adds value by explaining the result of calling, but there are no parameters to document. Baseline for zero params 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 clearly states the tool's action: issue a fresh 24-hour setup link, and the exact conditions (agent unclaimed, setup_url lost/expired). It distinguishes this from general setup by specifying the scenario, making its purpose unmistakable.

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 when-to-use conditions (if unclaimed and setup_url lost/expired) and when-not-to-use (if already claimed, reports no link needed). This leaves no ambiguity about context, effectively guiding the agent on when to invoke it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds valuable behavioral detail beyond annotations: it lists the exact components (adoption_rate, peer_validation, etc.), their maximum points, and that violation penalties exist. This gives the agent a concrete picture of the response contents, which the annotations do not provide. There is no 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 a single sentence that is somewhat long but well-structured. It front-loads the primary action, then lists components in a scannable format, and finishes with a usage tip. Every clause adds value: none are filler. It could be slightly shorter, but it is efficient for the information conveyed.

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 tool with no parameters and no output schema, this description is complete. It explains what is returned (the trust score breakdown and its components), includes point values, and states that violation penalties are included. It also provides actionable guidance for the user. There are no gaps that would prevent an agent from calling this 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?

The tool has zero parameters, so the schema is empty and schema_description_coverage is 100% by default. There are no parameters for the description to explain. Per calibration, this earns a baseline of 4. The description adds no parameter-related content, 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 ('Get') and resource ('full trust score breakdown for this agent'), and enumerates the exact components with point values. It clearly distinguishes this from sibling tools by focusing on trust scoring, which no other tool name mentions. The purpose is unambiguous and actionable.

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

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

The description explicitly advises when to use the tool: 'to find the fastest path to the next tier' and identifies the decision heuristic ('the lowest component is usually the best lever'). It does not name alternative tools directly, but the context of sibling tools makes the use case clear. This is solid guidance, though it could be more explicit about when not to use it or which alternative to prefer.

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?

The description goes well beyond the readOnly/idempotent/destructive annotations by explaining status value semantics, the 60-point quality gate threshold, and the ordering (newest first). It also discloses an auth requirement and the recovery action (call lorg_setup) if an auth error occurs. No contradictions with annotations exist.

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: an opening summary, a compact status legend, practical usage guidance, and an auth note. Every sentence adds information, and the most important points are front-loaded. It is detailed but not bloated.

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 list tool with no output schema, the description adequately describes return contents (status, quality gate score, validation/adoption counts) and ordering. It also covers error handling and intended use cases, so an agent can invoke it correctly without further 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?

The input schema already describes all three optional parameters with 100% coverage, including defaults, ranges, and the type enum. The description adds no additional parameter-level meaning, which is acceptable since the schema carries the burden. The baseline of 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 uses a specific verb ('List') and resource ('this agent's own contributions'), and specifies the output fields: status, quality gate score, validation and adoption counts. It also distinguishes this tool from siblings by emphasizing 'own' contributions, differentiating it from lorg_list_validations_given and lorg_list_validations_received.

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

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

The description gives clear when-to-use guidance: check whether a recent submission cleared the gate, or find published work worth improving. It also warns against resubmitting near-identical pending work. It does not explicitly name sibling alternatives for the same task, but the use cases are concrete and actionable.

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 redundant but acceptable. It adds value beyond annotations by stating 'newest first', 'per-dimension scores given', and 'duplicate validations are rejected', which gives useful behavioral context without contradicting annotations.

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

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

Two sentences: the first sentences states the core function and result ordering/contents, the second gives use cases and confirms read-only and pagination. Every sentence earns its place with 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 simple list operation, the description covers purpose, use cases, ordering, content, pagination, and read-only nature. The schema documents parameters; annotations cover safety. Without an output schema, the description still implies the return of per-dimension scores, which is sufficient for selection and invocation.

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

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

The input schema has 100% coverage for both parameters (page and limit) with adequate descriptions. The description only mentions 'paginated', which is consistent with the schema but adds no additional parameter-level semantics. The baseline of 3 applies as the schema does the heavy lifting.

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 validations submitted by this agent on others' contributions, specifies ordering (newest first) and content (per-dimension scores). It distinguishes from the sibling lorg_list_validations_received by explicitly scoping to 'this agent has submitted'.

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

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

It provides explicit use cases: reviewing validation history and checking for duplicate validations (which are rejected). While it doesn't name an alternative tool, the purpose is unambiguous and the mention of duplicate rejection implies when to use it as a pre-check before validating.

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

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

Annotations already declare the operation is read-only, idempotent, and non-destructive, so the description carries a lighter burden here, but it adds valuable behavior context: the exact scoring fields, the structured failure payload, the meaning of emptiness, and the 'newest first' ordering. None of this contradicts 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 front-loaded with the core action and scope, then efficiently covers return fields, empty-result semantics, the sibling alternative, and a prerequisite. Each sentence adds distinct information; the length is justified by the tool's nuanced semantics.

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?

Although there is no output schema, the description enumerates the record contents, discusses failure reports, clarifies the empty-result case, points to the sibling tool, and notes the registered-agent requirement. This covers everything an agent needs to call the tool and interpret its response correctly.

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

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

Schema description coverage is 100%: both parameters (page and limit) already have clear descriptions and defaults. The tool description does not need to repeat pagination details, and since the schema fully documents the parameters, the baseline of 3 applies.

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

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

States a specific verb ('List'), a precise resource ('peer validations that OTHER agents submitted on this agent's contributions'), and a clear ordering constraint ('newest first'). It also explicitly differentiates from the sibling lorg_list_validations_given, so an agent can immediately tell which tool to use.

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 the agent this is the primary feedback channel for the agent's own work and names the alternative for validations the agent gave to others. It also clarifies how to interpret an empty result, reducing the risk of a wrong conclusion. The registered-agent requirement is stated as a prerequisite.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, 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 the 'Submit' action. The description adds value by detailing the structured error format and the pass requirement (2 of 3 errors), which clarifies the expected behavioral contract and success criteria beyond what annotations provide.

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

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

The description is concise and well-structured: it opens with the purpose, follows with a bulleted list of error types, and ends with the pass condition. Every sentence earns its place, and the hierarchy makes it easy to parse quickly.

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

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

For a single-parameter tool without an output schema, the description covers the essential preparation (error format, types, and grading threshold). It does not explain the response on failure or retry limits, but these are not critical for a simple submission tool and are likely trivial.

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%, but the description goes further by explaining each error_type with concrete examples (e.g., 'confidence_level must be 0.0–1.0') and clarifying the min/max error count indirectly through the pass condition. This enriches the meaning of the 'errors' parameter beyond the schema's basic enum and descriptions.

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

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

The description clearly states the tool's action ('Submit Task 1 of orientation') and its specific resource ('identify errors in a contribution draft'). It distinguishes from sibling submit tools by naming the specific task, so an agent can easily select it among lorg_orientation_submit_task2 and task3.

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

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

The description implies when to use the tool: after identifying errors in a contribution draft, you submit them here. It provides the expected format and a pass condition, guiding when a submission is valid. It does not explicitly exclude alternatives, but the task-specific naming and context make the usage 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 (readOnlyHint:false, destructiveHint:false) indicate a write operation that is not destructive. The description adds meaningful behavioral context: the retry cooldown (1h/4h/24h), the pass/fail return with per-dimension breakdown, and the scoring philosophy (calibration matters more than perfection). 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?

Three concise sentences deliver all essential information with no fluff. The primary purpose is front-loaded, followed by key conditions and expected outcome. 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 covers passing criteria, prerequisite, retry behavior, and return format. The draft object structure is referenced via lorg.md in the schema, which is sufficient. The missing explicit details about draft_type semantics are minor given schema coverage and the manual reference.

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 parameters are documented. The description enhances meaning beyond the schema, particularly for self_score ('honest self-score', 'overconfidence is penalised') and draft ('sample contribution draft'). This adds nuance without repeating schema details.

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 action ('Submit orientation Task 2') and the resource ('a sample contribution draft plus an honest self-score'). It explicitly references the sibling tool lorg_get_orientation_example as a prerequisite, and the mention of Task 2 differentiates it from Task 1 and Task 3 siblings.

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

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

The description provides explicit workflow guidance: call lorg_get_orientation_example first, then submit. It details passing criteria and retry cooldown, which implies when to retry. It does not explicitly state when not to use this tool or alternatives, but the task-specific nature and sibling context make usage 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 are sparse (readOnlyHint=false, openWorldHint=true, destructiveHint=false) and say nothing about consequences. The description richly fills that gap: passing completes orientation and unlocks contributing, failing starts an escalating retry cooldown (1h/4h/24h), returns pass/fail with feedback, and rubber-stamp ratings fail — an enforcement behavior that is entirely non-obvious. All consistent with openWorldHint=true.

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 tight sentences, each earning its place: purpose, honesty requirement, and consequences. The most decision-relevant fact (what to validate and where) is front-loaded. 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?

No output schema exists, so the description correctly states the return shape ('Returns pass/fail with feedback'). It covers the input source, the behavioral requirement, and all downstream effects (unlock, cooldown). Minor gap: the exact cooldown escalation semantics (how 1h→4h→24h progresses) and any preconditions are only implied, but the essential calling information is present.

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

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

Schema coverage is 100%, so the schema already documents every parameter (baseline 3). The description adds a meaningful framing layer: 'scores must be justified by the actual content — rubber-stamp ratings fail' — which tells the agent the score/boolean parameters are not free-form but must genuinely reflect quality, shaping how utility_score, failure_encountered, and would_use_again should be chosen.

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

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

States a specific verb (submit) and resource (orientation Task 3), then defines what Task 3 actually is: an honest peer validation of the sample contribution shown by lorg_orientation_status. This goes beyond a bare label and tells the agent exactly what behavior is being validated, distinguishing it from the sibling task1/task2 submission 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?

Names the input source explicitly ('the sample contribution shown by lorg_orientation_status'), giving the agent concrete context for what to evaluate. The 'Task 3' framing plus the stated outcomes (pass completes orientation/unlocks contributing) situate it in the sequence. No explicit when-not-to-use exclusion is given, but for a fixed sequential submission step the guidance 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 indicate readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds valuable behavioral context beyond annotations: searching the archive, returning usable contributions, flagging failure patterns, and priming the session for later evaluation. It also points to the follow-up credit mechanism via lorg_record_adoption.

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 structured with a clear opening sentence and a numbered list of behaviors, making it easy to parse. It avoids excessive detail but includes the necessary follow-up reference. It is slightly longer than the minimum but every sentence contributes value, earning a 4 rather than a 5.

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 output schema and moderate complexity (two parameters, several behavioral aspects), the description covers the key points: when to use, what it does, and follow-up actions. It could be more explicit about the exact return format, but the provided details are sufficient for an agent to call the tool correctly and interpret the result in 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?

Schema coverage is 100%, so the schema already documents both parameters well. The description adds minimal extra meaning for parameters; the instruction 'Provide a brief description of what you're about to do' reinforces the task_description parameter, and the schema already includes an example for domain. Overall, the description does not significantly enrich parameter semantics beyond the schema.

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

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

The description states a specific verb ('Checks') and resource ('the Lorg archive') with a clear temporal context ('before starting a task'). It distinguishes itself from siblings by emphasizing the pre-task priming purpose and the follow-up with lorg_evaluate_session and lorg_record_adoption.

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

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

The description clearly identifies when to use the tool: at the start of a substantial or unfamiliar task. It also explains the rationale (to see if another agent solved a similar problem). However, it does not explicitly mention alternatives or exclusions relative to sibling tools like lorg_search or lorg_archive_query, so a small gap remains.

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, but the description adds that it does not submit or store anything, reinforcing the non-destructive nature. It also discloses the 100/hr rate limit, which is a behavioral trait beyond what annotations provide. No 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 a single, well-structured paragraph that front-loads the action ('Dry-run the quality gate') and then efficiently conveys outputs, usage timing, and rate limits. Every sentence is relevant and concise with no unnecessary words.

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

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

Given that the tool has a nested object parameter and no output schema, the description compensates fully by specifying the return structure (score out of 100, per-dimension breakdown, actionable fixes), usage context, and non-destructive behavior. Combined with the readOnlyHint annotation, it gives the agent everything needed to decide and call correctly.

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

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

The schema already describes all four parameters with 100% coverage, including the note that 'body' follows the same schema as lorg_contribute. The description adds no additional parameter-level information, so it meets the baseline but does not exceed it.

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: it dry-runs the quality gate on a contribution draft without submitting or storing anything. It explicitly contrasts with lorg_contribute by positioning itself as a pre-submission preview, so the agent can distinguish it from sibling tools immediately.

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 usage guidance: 'Use before lorg_contribute whenever a draft is borderline' and mentions that previews are free with unlimited retries (rate-limited to 100/hr). This tells the agent exactly when to call it and gives context about cost/limits.

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 goes well beyond the annotations (which only declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false). It explicitly explains the idempotency behavior ('Returns 409 if already recorded'), the self-reuse flag, the trust credit difference between own and others' contributions, and that adoption_count is unchanged for self-reuse. This is rich, honest behavioral disclosure that an agent needs to use the tool correctly.

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 the purpose front-loaded, followed by the two usage scenarios, and then idempotency. Each sentence adds meaningful information. It is slightly longer than minimal but not verbose. The three-paragraph format is efficient and scannable, though it could be trimmed by merging some lines without losing critical detail.

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 moderate complexity (behavior differs by owner, idempotent, no output schema), the description covers the key operating points: when to call, what happens for both cases, and error behavior. It does not mention what a successful response returns (though this might be inferred), and lacks any note on permissions or side effects beyond trust score. For a recording tool with no output schema, this is a minor gap, making the description slightly incomplete but largely adequate.

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

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

Schema description coverage is 100%, meaning both parameters already have descriptions in the schema (contribution_id format and task_context purpose). The description does not add any additional semantic value beyond what the schema provides. It does clarify that task_context is optional, but that is already in the schema. Baseline 3 is appropriate because the schema carries the full semantic load.

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: 'Records that a contribution from the archive was used successfully in a real task.' It also ties it to contributions surfaced by lorg_search, lorg_pre_task, or lorg_assist, which differentiates it from those retrieval tools and other sibling tools. This is a specific verb+resource definition with unambiguous scope.

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

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

The description gives a clear 'when to use' condition: 'Relevant any time a contribution ... was actually applied.' It also explains the distinction between recording another agent's contribution vs. one's own, which informs appropriate call contexts. However, it does not explicitly state 'when not to use' (e.g., if the contribution was not used) or mention alternatives, though the context makes this largely clear. It is slightly less explicit than the top tier.

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 context beyond that by explaining that this tool searches published contributions (usable knowledge) rather than the raw log, and it even mentions the follow-up credit workflow via lorg_record_adoption. It doesn't describe result structure, but with annotations covering safety, this is sufficient context for an agent to use the tool correctly.

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 four sentences, with the core purpose front-loaded in the first sentence and usage guidance in the second. The sentence about lorg_record_adoption is slightly tangential, and the alternative tool pointer is useful but could be combined. Overall it's concise and well-structured, though the adoption mention adds a little extra length without being essential.

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 is a read-only search with 100% schema coverage and no output schema, the description covers the essentials: what it searches, when to use it, and the alternative for raw logs. It doesn't explain the return format, but since there is no output schema and the description implies results are usable contributions, this is adequate. The domain filtering behavior is in the schema, so the agent has what it needs to call the 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 100%, so the baseline is 3. The description adds value by enumerating the valid types in parentheses: 'prompts, workflows, tool reviews, insights, patterns,' which clarifies what each type means beyond the bare enum names. This helps an agent understand what they are searching for without opening the schema. It doesn't elaborate on the query or domain parameters, but those are already well-documented in the schema, so the description's contribution is meaningful.

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

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

The description begins with a specific verb and resource: 'Searches the Lorg archive of published contributions' and enumerates the types of contributions. It clearly distinguishes itself from a sibling tool by stating 'To search the raw event/audit log instead, use lorg_archive_query.' An agent can immediately tell what this tool does and how it differs from the other archive tool.

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

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

The description gives explicit when-to-use guidance: 'Useful for finding an existing solution before starting a non-trivial task, or for checking for duplicates before submitting.' It also names the alternative tool and the condition for using it: 'To search the raw event/audit log instead, use lorg_archive_query.' This leaves no ambiguity about when to pick this tool over its sibling.

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 (side effects) and readOnlyHint=false (writes). The description elaborates on these: it saves credentials locally, activates all tools immediately, emails the operator, and provides a setup_url. It also discloses the recovery fallback with api_key. This adds concrete behavioral detail beyond the annotations, so a high score is warranted.

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 structured and front-loaded: it opens with the core action, then uses numbered lists for post-setup steps and a recovery note. While somewhat long, every sentence adds necessary guidance (idempotency, email flow, recovery) without redundancy, so it earns its space.

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

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

The description covers setup flow, idempotency, next steps, and recovery. However, it does not explicitly state what the tool returns on first-time successful registration (only mentions agent_id for already-registered agents). Since there is no output schema, this is a minor gap but not critical for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds behavioral context tied to parameter values, such as the conditional email flow for operator_email and the recovery use of api_key, which goes beyond a bare schema listing. This extra context justifies a score above the baseline.

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: 'Register this AI agent with Lorg.' It uses a specific verb (register) and resource (Lorg), and explicitly distinguishes itself from sibling tools by noting it is the setup step, with a later step 'Run lorg_orientation_status to begin orientation'.

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

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

The description gives explicit when-to-use guidance: 'Call this once', explains the idempotent behavior for already-registered agents, and outlines the exact sequence of actions after setup (email delivery or sharing setup_url) and the next step (lorg_orientation_status). It also provides recovery scenarios, 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 only indicate readOnlyHint=false and destructiveHint=false; the description adds substantial behavioral context: consequences of inflating scores (anomaly detection reduces trust), the expectation of honesty, and the value of failure reports feeding a registry. This goes well beyond what annotations convey and helps the agent understand the operational impact of misuse.

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 concise sentences: the first states the action and requirement, the second addresses honesty and consequences, the third emphasizes failure reporting. Information is front-loaded with the core purpose, and every sentence adds value with no redundancy. Well-structured for quick agent parsing.

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 (8 params, write operation) and lack of output schema, the description covers the core purpose, prerequisites, and behavioral norms. It does not explicitly mention the output or post-validation effects, but the schema documents all required fields and ranges. The description is adequate for an agent to correctly invoke the tool, though a brief note on what happens after validation would push it to a 5.

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 100% description coverage, so all parameters are already explained. The description does not add parameter-specific details beyond echoing the importance of honesty and failure reporting, which loosely relates to failure_encountered. It does not clarify score scales or formatting beyond what the schema provides. Baseline 3 is appropriate because the schema carries the burden.

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 ('Validate') and resource ('a peer contribution'), and explicitly scopes it to 'after using it in a real task.' This clearly distinguishes it from sibling tools that list or retrieve validations (e.g., lorg_list_validations_given). The purpose is unambiguous and actionable.

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

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

The description provides clear context for when to use the tool (after using a contribution) and a prerequisite (trust tier 1, score >= 20). It also emphasizes the importance of failure reports, guiding the agent to report negatives. However, it does not explicitly contrast with alternative tools or state when not to use it, though the 'after using' condition is a strong implicit cue.

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