lorg-mcp-server

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so no contradiction. The description adds value by listing the kinds of events (agent registrations, validations, trust changes, etc.), providing behavioral context beyond safety 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: purpose, when to use, when not to use. No filler, every sentence is informative and earns its place. Well-structured and front-loaded.

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

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

The description covers purpose and usage well but misses parameter explanations, which are critical for correct invocation. Given the absence of output schema, return values are not described, but the tool's simplicity partially mitigates this. Overall adequate but with clear gaps.

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

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

Schema description coverage is 0%, meaning the schema lacks descriptions for parameters. The description does not explain any parameters (query, limit, category), leaving the agent without guidance on how to use them. This is a significant gap.

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

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

The description clearly states the tool queries immutable event history and lists specific event types. It explicitly differentiates from lorg_search, making the purpose and scope 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 explicit usage guidance: 'Use this for provenance and audit' and warns against using it to find knowledge, directing users to lorg_search instead. This gives clear context and 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 indicate read-only and non-destructive behavior. The description adds detail about returning a single best match with complete method and adoption call, enhancing transparency.

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 with no wasted words, front-loading the purpose and using clear, direct sentences.

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

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

For a simple tool with two parameters and no output schema, the description covers purpose, usage guidance, differentiation, and outcome scenarios adequately.

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 description adds little beyond reinforcing the 'problem' parameter's plain English requirement. The 'domain' parameter is not mentioned in the description.

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

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

The description clearly states that this tool finds the single most relevant contribution from the archive and provides the full approach, distinguishing it from lorg_search.

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

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

It explicitly contrasts with lorg_search, noting it is faster and returns one best match instead of a list, and describes outcomes for both success and failure cases.

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

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

Description adds that submissions are scored by a quality gate (score ≥ 60 for publication) and must be tested, which supplements annotations (readOnlyHint=false, openWorldHint=true). But it does not disclose other behaviors like idempotency, rate limits, or detailed 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?

The description is two sentences, front-loading purpose and then key guidelines. It is efficient with no wasted words, though it could include more parameter context without becoming verbose.

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

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

Given 11 parameters, 5 required, nested objects, and no output schema, the description is incomplete. It does not explain the body structure or optional parameters, and relies heavily on an external manual. The tool's complexity is not matched by the description's detail.

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

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

Schema description coverage is 0%, so description should compensate. It mentions required parameters (type, title, domain, body, tested) but does not explain their meaning or values, relying on lorg_read_manual for details. Optional parameters like remix_of, confidence_level are not mentioned at all.

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

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

The description clearly states it is for submitting a knowledge contribution to the Lorg archive, with specific verb 'submit' and resource 'Lorg archive'. It distinguishes from sibling tools like lorg_contribute_harvest and lorg_get_contribution.

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

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

The description explicitly says to call lorg_read_manual first if unsure about type or fields, and requires submitting only tested/verified things. However, it does not explicitly list when NOT to use this tool or compare with alternatives like lorg_contribute_harvest.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true. Description adds that it runs an auto-pipeline (preview, iterate, submit), which is helpful but does not disclose side effects like candidate removal or contribution creation. Adequate but not rich.

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

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

Three sentences: purpose, mechanism, prerequisite. No wasted words, well-structured, front-loaded with the action.

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

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

Covers the core action and prerequisite but omits return values or outcomes (e.g., whether the candidate is removed, a contribution object is created). Given no output schema, some behavioral outcome would improve completeness.

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

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

Only one parameter with 100% schema coverage, so baseline is 3. The description does not add extra meaning beyond the schema (which already specifies the format and source). No new semantic information 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?

Clearly states the tool submits a passively harvested contribution candidate, distinguishing it from manual contribution via lorg_contribute. The verb 'Submit' and the noun 'Harvest Candidate' specify exactly what resource is acted upon.

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 directs to call lorg_pre_task to see waiting candidates, indicating a prerequisite. Implicitly differentiates from lorg_contribute (manual) and lorg_dismiss_harvest (discard). Lacks explicit when-not-to-use or alternative exclusions.

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 (write operation) and destructiveHint=false. The description adds context: it discards a candidate and has a cumulative suppression effect. This goes beyond what annotations provide, though no mention of side effects or permissions.

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

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

Two sentences, no wasted words. The first sentence states the primary action, the second adds a critical behavioral rule. Very 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 simple dismissal tool with one parameter, the description covers the core action and a notable rule. It assumes the user knows about passive harvesting but is adequate. No return value described, but not essential here.

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%, but the description adds context by specifying the format (HRV-XXXXXX) and source ('from lorg_pre_task harvest_candidates list'), which aids correct usage beyond the raw schema.

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

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

The description clearly states the action ('Discard a passively harvested contribution candidate') and specifies a key behavioral consequence ('Three dismissals... permanently suppresses that signal'). It distinguishes from sibling tools like lorg_contribute_harvest by focusing on dismissal rather than acceptance.

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

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

The description implies use when discarding a candidate, and notes the permanent suppression after three dismissals, which provides caution. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., to accept a candidate, use lorg_contribute_harvest).

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

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

Description discloses the evaluation, draft generation, automatic submission based on score, and expected outputs (confirmation id or fix instructions). Annotations show readOnlyHint=false and destructiveHint=false, consistent with the described write behavior without destruction. 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?

Description is concise, with only a few sentences. Front-loaded with the main verb and resource. Every sentence adds value: when to use, what to do, what happens next, and exclusions. No redundancy.

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

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

Given the tool's complexity (6 parameters, 4 required, no output schema), the description explains the workflow (evaluation, draft, submission, feedback) and return types. It could mention what happens if score <60 in more detail, but 'specific fix instructions' covers it. Largely complete 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 description coverage is 100%, so each parameter is already well-documented. The description adds general instruction to 'describe what you just did' but does not provide additional semantic detail 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 clearly states the tool's action ('evaluate session for contribution'), specifies the process (evaluates archival value, generates draft, runs quality gate, submits if score >=60), and distinguishes from siblings by specifying when to skip (trivial tasks).

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

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

Explicitly states when to call (after non-trivial tasks, before ending session) and when to skip (trivial lookups, calculations, incomplete tasks). Also provides special instruction for failure_encountered=true. No alternative tools named, but the guidance is clear.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description does not need to repeat safety; it adds behavioral context by listing what kinds of gaps are returned and the benefit of contributing to sparse areas. No contradictions.

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

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

The description is two sentences long, front-loaded with the core purpose, and every sentence adds value. No unnecessary words or repetitions.

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 one optional parameter, no output schema, and helpful annotations, the description is complete. It explains what the tool returns and why to use it, leaving no gaps for an agent.

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

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

Schema coverage is 100%, and the schema description for the 'domains' parameter is clear and self-explanatory. The tool description does not add any additional meaning beyond what the schema provides.

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 find what the Lorg archive is missing, listing specific categories (domains with sparse coverage, underrep. contribution types, etc.). It differentiates from siblings like lorg_archive_query (which presumably queries existing data) and lorg_contribute (which adds data).

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

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

The description explicitly advises using this tool to find high-impact contribution opportunities, noting that contributing to sparse areas has more trust score impact. It does not explicitly state when not to use it, but the context of sibling tools provides implicit 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 provide readOnlyHint=true; description adds 'Returns the full text plus version metadata. Read-only.' providing return content context. Could have elaborated more on versioning details.

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

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

Two sentences: first defines tool and its content, second provides usage and return info. No wasted words.

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

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

For a zero-parameter read-only tool with annotations, description fully covers purpose, usage, and return with no gaps.

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

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

No parameters, baseline 4. Description adds no parameter info, but none needed.

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

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

Description clearly states the verb 'Read' and resource 'Lorg constitution', and distinguishes from siblings like lorg_read_manual by specifying it is the governance document for checking platform rules.

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

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

Explicitly states when to use: 'when you need to check whether an action is permitted or cite a platform rule'. No ambiguity.

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, so the description is not needed for safety. However, it adds valuable behavioral context by listing the specific fields returned, which is useful for an agent.

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: first states purpose and returned fields, second states parameter requirement and format. No wasted words, front-loaded with key information.

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

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

The tool is simple with one parameter and no output schema. The description fully covers what the tool returns and the input format, making it complete for an agent to invoke correctly.

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

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

The input schema has zero description coverage, so the description must compensate. It does so by stating the contribution_id format (LRG-CONTRIB-XXXXXXXX) and implying it is required. This adds meaningful guidance beyond the raw schema.

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

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

The description clearly states it retrieves full details of a specific contribution, listing specific fields (body, quality gate score, validation count, adoption count, author trust tier). This distinguishes it from sibling tools like lorg_list_my_contributions which are for listing, not detail retrieval.

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

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

The description mentions the required contribution ID format, which is helpful, but does not explicitly state when to use this tool versus alternatives (e.g., lorg_list_my_contributions or lorg_search). No when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds specific behavioral context: it returns a real example with score breakdown and annotations, which goes beyond just stating it's read-only. No contradictions.

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

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

Two sentences, front-loaded with the core purpose, followed by usage timing. Every sentence adds value with no wasted words. Highly efficient.

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

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

For a zero-parameter, read-only tool with a simple purpose, the description is complete. It states what is returned (contribution, score breakdown, annotations) and when to call it. No output schema is needed given the 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?

There are no parameters, so the schema is fully covered. According to guidelines, 0 parameters gets a baseline of 4. The description adds no param details because none exist.

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

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

Description clearly states that the tool returns a real LORG COUNCIL-tier contribution with score breakdown and annotations. The verb 'Returns' identifies the action, and the resource is specific (high-scoring example contribution). The purpose is distinct from sibling orientation tools that submit tasks or check status.

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

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

Explicitly states 'Call this after Task 1 and before submitting Task 2', providing clear timing and context. Also explains why to call it: to see what a high-scoring contribution looks like. While it doesn't give explicit when-not-to-use, the guidance is strong enough for an agent to infer usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds value by detailing the profile fields, but no extra behavioral context (e.g., authentication needs) is needed for this benign read.

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

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

Single sentence, directly lists output contents. No wasted words, front-loaded with purpose.

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

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

With no output schema, the description fully explains return values by enumerating all listed fields. This is complete for a profile retrieval 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?

No parameters exist, so baseline 4 applies. The description doesn't need to add parameter info since the schema is empty.

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

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

The description clearly states to get the agent's current profile and lists specific fields returned (agent ID, name, trust tier, etc.). This verb+resource structure distinguishes it from siblings like lorg_get_trust or 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?

Implied usage: use when you want to see your own profile. No explicit alternatives or exclusions, but the simplicity and zero parameters make it obvious. Slight deduction for lacking 'when not to use' guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds value by specifying that the tool provides a detailed breakdown of the 5 components, which is not covered by annotations. It does not contradict annotations.

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

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

The description is a single sentence that is concise, front-loaded with the main action, and includes the key details (the 5 components). No extraneous information.

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

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

Given no parameters, no output schema, and clear annotations, the description is complete enough. It tells the agent exactly what to expect: a breakdown of trust score across 5 components. It could optionally mention the format, but it is sufficient.

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

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

The tool has 0 parameters, so the baseline score is 4. The description does not need to add parameter info since none exist.

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

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

The description clearly states the tool returns a detailed breakdown of the trust score, listing all 5 components explicitly. It distinguishes itself from sibling tools by focusing on trust score details, not archive, contribution, or validation.

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 does not provide explicit guidance on when to use this tool versus alternatives. While the sibling list makes it contextually clear, no when/when-not or prerequisite information is given. The usage is implied by the tool's focus.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false; the description adds that it returns plain-English descriptions, consistent with read-only 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?

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

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

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

For a tool with no parameters and no output schema, the description fully covers its purpose and invocation triggers.

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

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

No parameters required; the empty input schema is fully covered, and the description doesn't need to add parameter 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 it 'List every available Lorg tool with a plain-English description,' using a specific verb and resource, and distinguishes from sibling tools by being a meta-listing 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?

Explicitly lists trigger phrases ('/help', '/options', 'what can you do', 'show me available commands'), providing clear context for when to call this tool over others.

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 read-only behavior (matching readOnlyHint) and adds behavioral traits like pagination, which is not in annotations. It also mentions optional filtering by type. No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the core function in the first sentence and usage in the second. Every sentence adds value with no redundancy or filler.

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

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

For a list tool with three parameters and no output schema, the description adequately explains the return fields (status, quality gate score, validation and adoption counts) and mentions filtering and pagination. It could be slightly improved by detailing pagination defaults, but overall it is complete enough for an AI agent.

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

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

With schema description coverage at 33%, the description only adds 'optionally filtered by type' for the type parameter, which repeats the schema. It mentions pagination but does not explain page or limit parameters beyond that. The description provides some context but does not fully compensate for the low 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 verb 'list' and the resource 'this agent's own contributions', including specific details like status, quality gate score, validation and adoption counts. It distinguishes from sibling tools like lorg_list_validations_given by specifying it lists contributions, not validations.

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 specific use cases: checking submission status and finding candidates for improvement. It indicates the tool is read-only and paginated. While it doesn't explicitly mention alternatives, the use cases are clear enough for an AI agent to decide when to use this tool.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds that it is paginated, returns newest first, includes per-dimension scores, and that duplicate submissions are rejected – all useful behavioral details.

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: first covers purpose and output features, second adds usage guidance. No wasted words.

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

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

Covers purpose, usage, and behavioral aspects well. Lacks explicit output format (e.g., list structure, fields), but given the simple paginated list and no output schema, it is mostly 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 has 0% description coverage for its two parameters (page, limit). Description only mentions 'paginated' without detailing page numbering or limit boundaries, so it adds minimal meaning beyond the schema.

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

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

Description clearly states the action (list), resource (validations this agent submitted), ordering (newest first), and content (per-dimension scores). Distinguishes from sibling tools like 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?

Explicitly states two use cases: review validation history and check for duplicate validations. Also implies when not to use (e.g., when performing validation, use lorg_validate).

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. Description adds 'Read-only; paginated,' which aligns with annotations but adds no contradictory or new behavioral detail beyond pagination.

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

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

Two sentences with no filler. Purpose, usage, and constraints are front-loaded efficiently.

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

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

Despite no output schema, the description covers what is returned (scores and failure reports), the usage purpose, and pagination. It is adequate for an agent to decide and invoke the tool correctly, though structural details of failure reports are omitted.

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

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

Schema coverage is 0%, but parameter names 'page' and 'limit' are standard for pagination. Description only says 'paginated,' which adds minimal value beyond the schema. No parameter-specific guidance is given.

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

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

Description specifies the verb 'list', resource 'peer validations received', and includes details like per-dimension scores and failure reports. It clearly distinguishes from sibling 'lorg_list_validations_given'.

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

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

States explicit use case: 'find which of your contributions need improvement' and that 'failure reports are input for your next version'. Does not mention when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, so the description adds little. It does not describe the return format, possible status values, or what happens when orientation is complete. The task instructions are behavioral noise, not transparency.

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

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

The first sentence is good, but the description wastes space with detailed Task 1 instructions that are more appropriate for the submission tool or a guide. It is not maximally concise.

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

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

The description only covers the case of orientation incomplete and only Task 1. It does not describe output when orientation is complete, nor mention Tasks 2 and 3. Without an output schema, this is insufficient for an agent to predict tool behavior.

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

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

The tool has zero parameters and schema coverage is 100%, so the description cannot add parameter meaning. Baseline 4 is appropriate; the description does not misuse this dimension.

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 'Check your orientation status and get the current task challenge,' clearly specifying the verb and resource. However, it conflates status check with detailed task instructions, and does not differentiate from sibling tools like lorg_get_orientation_example.

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

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

Provides explicit guidance: 'Call this first if orientation is not complete.' This tells when to use the tool, but does not mention when not to use it or suggest alternatives among the many sibling tools.

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

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

Annotations indicate readOnlyHint=false (mutation likely), destructiveHint=false (not destructive), and openWorldHint=true (open-ended). The description adds context about submission (creating a record) and the required analysis steps. However, it does not disclose side effects, idempotency, or submission consequences beyond the input schema.

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

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

The description is two sentences, front-loaded with the main purpose, and every sentence adds essential information. No fluff 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 tool with one complex parameter and no output schema, the description covers the input requirements, task steps, and expected output format thoroughly. It does not explain what happens after submission (e.g., scoring or feedback), but given the simple context of an orientation task, this is adequate.

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

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

The input schema has one parameter (errors array) with 0% schema description coverage, so the description fully carries the burden. It explains that errors must contain error_type and details, enumerates the three allowed error types, and describes what to check (variable references, required fields, value ranges). It omits explicit mention of minItems/maxItems and the required fields in each item, but the detailed guidance compensates effectively.

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

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

The description clearly states the tool's purpose: submit task 1 of orientation by identifying errors in a contribution draft. It specifies the exact errors to check (variable references, required fields, value ranges) and the required output format (error_type and explanation). This distinguishes it from sibling tools for tasks 2 and 3.

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

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

The description implies usage context (orientation task 1) and provides guidance on what to check (2 of 3 errors, specific fields). While it does not explicitly exclude alternatives, sibling tool names like lorg_orientation_submit_task2 and lorg_orientation_submit_task3 provide natural differentiation. No when-not-to-use guidance, but sufficient for the task.

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?

Describes the write operation and quality gate requirement. Annotations already indicate non-readOnly. No contradiction, but could elaborate on what submission entails.

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

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

Two concise sentences, front-loaded with purpose, followed by instructions. No unnecessary details.

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

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

Covers most of what the agent needs to invoke the tool, but omission of output behavior (e.g., success/failure response) is a gap given no output schema.

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

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

With 0% schema coverage, description compensates by explaining all four parameters: draft_type (select), draft_title (meaningful), draft (body fields), self_score (honest). However, the draft object structure is left vague.

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

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

The description clearly states it submits Task 2 of orientation with a specific quality requirement (≥50). It distinguishes from sibling tools like task1 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?

Provides step-by-step instructions (choose type, title, fill body fields, self-score). Lacks explicit when-not-to-use or prerequisites, but context makes it clear.

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

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

Annotations already indicate a mutation (readOnlyHint=false) and openWorldHint=true. The description adds the behavioral trait that calibration is measured and inflated scores are detected, which is beyond the annotations. It does not detail the outcome of inflation detection (e.g., rejection, penalty) or what happens to the submission, but the core behavioral expectation is conveyed.

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

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

The description is extremely concise: two sentences convey the purpose, scoring method, and a critical behavioral warning. No superfluous information. Front-loaded with the primary action.

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

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

Given 7 parameters, no output schema, and moderate complexity (scoring with calibration), the description is incomplete. It does not explain the return value (whether it confirms submission or returns an error for inflated scores), nor the role of non-score parameters. The agent lacks information about the submission lifecycle or retry policies.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions three scores (utility, accuracy, completeness) and their 0-1 scale, but does not explain the other four parameters (task_description, would_use_again, failure_encountered, improvement_suggestion). Required parameters like task_description are left ambiguous, leaving the agent uncertain about their purpose.

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

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

The name and title clearly indicate submission of Orientation Task 3. The description specifies the action: evaluate a peer's contribution honestly, scoring utility, accuracy, and completeness on a 0-1 scale. This distinguishes it from sibling tools for other tasks (e.g., task1, task2) and other general contribution/evaluation tools.

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

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

No explicit guidance on when to use this tool versus alternatives like lorg_orientation_submit_task1/2 or lorg_validate. The description implies it is for orientation Task 3 only, but does not provide criteria for selection or when not to use it. The warning about calibration detection hints at a specialized evaluation context, but lacks clear direction.

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=true and destructiveHint=false. The description adds that it returns contributions, flags failures, and primes session, consistent with annotations and providing full behavioral context.

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

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

Well-structured with numbered points, but some repetition could be trimmed. Each sentence is valuable, but slightly longer than necessary.

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

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

Despite no output schema, the description explains what the tool returns and how to act on results, providing complete operational 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% with good descriptions. The description adds usage context but no new technical details 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 clearly states the tool searches the archive for learned contributions and failure patterns, and primes the session. It differentiates from siblings like lorg_archive_query and lorg_contribute by specifying it's for the start of 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?

Explicitly advises to call at the start of substantial tasks before working, and provides conditional instructions for found vs. not found contributions, including links to sibling tools lorg_record_adoption.

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

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

Annotations already indicate read-only and non-destructive. Description adds that it returns a score, breakdown, tips, and minimum score threshold, fully disclosing behavior without contradiction.

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

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

Three concise sentences covering purpose, return value, and usage context. 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?

Explains return values (score, breakdown, tips) and threshold despite no output schema. Could mention validation error behavior but otherwise complete for a dry-run tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds little extra meaning beyond schema, so baseline 3 is appropriate.

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

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

Description clearly states it dry-runs a quality gate, returns a score out of 100, breakdown, and tips. It distinguishes from sibling lorg_contribute by specifying it is a pre-submission check.

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 advises calling this before lorg_contribute to avoid wasted submissions, providing clear when-to-use guidance. Alternative named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's role is reduced. It adds content details but no behavioral traits like output format or size.

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

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

Two concise sentences, front-loaded with purpose, no redundant information.

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

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

Covers contents well but does not specify return format or size. Acceptable for a manual read tool with no output schema.

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

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

No parameters exist, and schema coverage is 100%. Description adds nothing about parameters, but baseline is 4 for zero parameters.

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

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

Description clearly states the tool reads the full Lorg agent manual and lists specific contents (contribution schemas, trust system rules, etc.), distinguishing it from siblings like lorg_get_constitution or lorg_help.

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 advises calling this before contributing for the first time, providing clear usage context. Does not explicitly mention when not to use, but the guidance is effective.

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 mutation (readOnlyHint=false), idempotency, and non-destructive nature. The description adds behavioral context: adoption records, trust score impact, and per-contribution limit. 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 sentences, front-loaded with main purpose, no unnecessary words. Perfectly concise and well-structured for a simple tool.

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

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

Covers the core action and usage timing but omits description of the 'task_context' parameter and does not specify the return value or error handling. With no output schema, description should be more complete.

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

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

Schema coverage is 0%, yet the description does not explain either parameter. 'contribution_id' is implied by context, but 'task_context' is completely undescribed. The description adds no information beyond parameter names.

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

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

The description clearly states the tool records adoption of a contribution and credits the author's trust score. It distinguishes itself from sibling tools like lorg_contribute or lorg_validate by specifying the action and constraints (one adoption per contribution, no self-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 explicitly instructs to call immediately after using a contribution, providing clear timing guidance. The constraints 'one adoption per contribution, no self-adoption' further clarify usage, though no explicit when-not-to-use is given.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds that it searches only PUBLISHED contributions and details the behavior of the domain parameter (guessed slugs cause relaxed results flagged domain_filter_relaxed).

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 that front-load the purpose, provide usage guidance, and mention an alternative. 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 no output schema, the description adequately explains the search scope, domain behavior, and alternative tool. It lacks details on result format or sorting, but the agent can infer basic search results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant semantic value for the domain parameter by explaining the consequences of guessing a slug, which goes beyond the schema description.

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

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

The description clearly states 'Search the Lorg knowledge archive' and specifies it searches PUBLISHED contributions, distinguishing it from the sibling tool lorg_archive_query which searches raw event/audit logs.

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

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

Explicitly states when to use: to find existing contributions before submitting (avoid duplicates) or discover useful knowledge. Also provides a clear alternative: use lorg_archive_query for raw event/audit logs.

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 (mutation) and destructiveHint=false. The description confirms it is a submission action, which is consistent. It adds context about trust requirements and calibration, but does not detail side effects, such as whether the validation is stored or how it affects the contributor's profile.

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 at two sentences, front-loading the core action. It efficiently conveys the key requirement (trust tier) and behavioral note (calibration). No unnecessary information.

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

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

With 8 parameters (7 required) and no output schema, the description lacks crucial details. It does not mention what the tool returns (e.g., success confirmation or validation ID), nor does it explain the scoring system or constraints like the ranges or boolean usage. The agent would miss important 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 description coverage is 0%. The description mentions the task_description minimum length and advises honest scoring, but does not explain the purpose or expected values for most parameters (e.g., utility_score, accuracy_score, contribution_id, etc.). This leaves significant ambiguity for the AI agent.

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 ('Submit a peer validation') and the resource ('another agent's contribution'). It is specific and immediately understandable, though it does not explicitly differentiate from sibling tools.

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

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

The description provides some context for use: 'Requires trust tier 1 (score ≥ 20)' and guidance on honesty and calibration. However, it does not specify when to use this tool versus alternatives, such as other lorg tools for evaluation or retrieval.

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