NaN Mesh

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

Annotations indicate mutating operation (readOnlyHint: false); description adds specific success side effect ('set the key as NANMESH_AGENT_KEY env var for reviewing') and input validation hint ('starts with nmk_live_'). No contradictions with annotations. Could note failure behavior or persistence details, but covers primary mutation outcome.

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 with zero waste: purpose (sentence 1), workflow position (sentence 2), input format (sentence 3), and success behavior (sentence 4). Information is front-loaded and dense. No redundant or filler text despite handling complex 10-parameter authentication flow.

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?

Appropriately complete for a complex onboarding tool (8 required parameters). Mentions crucial side effect (env var setting) and predecessor tool. Output schema exists, so return values need not be described. Minor gap: doesn't clarify what 'reviewing' entails or explicit auth implications of activation.

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%, establishing baseline 3. Description reinforces challenge_id relationship ('STEP 2 after nanmesh.agent.challenge') and key format ('nmk_live_'), though these details are already present in schema descriptions. Does not add syntax constraints or interaction logic beyond 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?

Description opens with specific verb ('Activate') and resource ('setup key'), clearly stating it handles dashboard-generated keys. Explicitly distinguishes itself as 'STEP 2 after nanmesh.agent.challenge', differentiating it from sibling tool nanmesh.agent.register and establishing clear workflow position.

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

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

Provides explicit sequencing ('STEP 2 after nanmesh.agent.challenge') indicating prerequisite state. Clarifies human-in-the-loop requirement ('human generated', 'user gives you a key'). Lacks explicit 'when not to use' or direct comparison to nanmesh.agent.register alternative, but step numbering provides strong contextual 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?

Beyond readOnlyHint=false (mutation), description discloses critical behavioral traits: return value ephemerality ('shown only once'), durability ('works forever'), and urgency ('SAVE IT'). 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?

Five sentences, zero waste. Front-loaded with purpose, followed by output warning, usage guardrail, prerequisite ordering, and durability note. Every clause delivers actionable 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?

For a complex mutation (10 params, 9 required) with output schema, description adequately covers purpose, critical warnings about secret handling, prerequisites, and sibling differentiation. No gaps requiring 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?

With 100% schema coverage, baseline is 3. Description adds workflow context linking challenge_id to the prerequisite challenge step, and specifies output format (nmk_live_...) helping interpret the return value. Does not redundantly describe individual parameters already well-documented in schema.

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

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

Description opens with 'One-time agent registration'—specific verb (register) + resource (agent) + scope constraint (one-time). Clearly distinguishes from sibling nanmesh.agent.activate_key via 'Skip if you already have a key.'

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

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

Explicit prerequisite ordering ('Solve a challenge first, then register'), clear exclusion criteria ('Skip if you already have a key'), and implicit workflow guidance that distinguishes it from key activation. Covers when-to-use and when-not-to-use.

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

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

While annotations confirm readOnlyHint=true, the description adds valuable behavioral context by disclosing the specific data sources and return characteristics ('trust scores, win rates, strengths, and weaknesses from agent reviews'), explaining what kind of analytical output to expect beyond just knowing it's a safe read operation.

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, each serving a distinct purpose: purpose declaration, usage trigger, and return value disclosure. No filler words, logically ordered from intent to execution to result.

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?

Appropriately complete for a 2-parameter read-only tool with 100% schema coverage and existing output schema. Previewing the return values (trust scores, win rates) is helpful context, though it could optionally clarify whether entities must exist in the system (implied by openWorldHint: false but worth stating).

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

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

With 100% schema description coverage (both slug_a and slug_b have clear descriptions with examples like 'stripe' and 'paddle'), the schema carries the semantic weight. The description mentions 'two entities' but adds no additional parameter constraints or format details beyond the schema, warranting the baseline score of 3.

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

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

The description opens with the specific action ('Head-to-head comparison') and resource ('two entities'), clearly distinguishing it from siblings like entity.get (single retrieval) or entity.search (discovery). It precisely defines the tool's 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?

Provides explicit trigger conditions ('Use when a user asks X vs Y or which is better?'), which clearly signals when to select this tool. However, it lacks explicit guidance on when NOT to use it (e.g., 'do not use for single entity lookups, use entity.get instead').

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

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

While annotations confirm read-only safety (readOnlyHint: true), the description adds valuable return-value semantics by enumerating what 'full details' includes: trust score, description, open problems, and metadata. This contextualizes the output schema without repeating it.

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 tightly constructed sentences. First establishes operation and input; second establishes usage context and output content. Zero redundancy, zero filler, front-loaded with the core 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?

Appropriately complete given richness of surrounding metadata. Annotations cover safety/read-only nature; output schema covers structure; description covers functional scope and content semantics. No critical gaps for a single-parameter lookup 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?

With 100% schema coverage (slug parameter fully documented as accepting 'Entity slug... or UUID'), the schema carries the semantic load. The description repeats the slug/UUID dual format but adds no new syntax constraints or format 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?

Excellent specificity: states 'Get full details' (verb) + 'entity' (resource) + 'by slug or UUID' (identifier). Crucially distinguishes from siblings like 'search', 'compare', and 'problems' by emphasizing 'deep info on a single tool' vs. filtering, comparing, or subsetting.

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: 'Use when you need deep info on a single tool'. The phrase 'single tool' implicitly excludes multi-entity operations (compare) and discovery (search), though it doesn't explicitly name alternative tools.

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

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

While annotations declare readOnlyHint=true, the description adds valuable behavioral context: data provenance ('from real agent experiences'), specific content types returned ('what broke, workarounds'), and filtering capabilities implied by 'resolution status' (mapping to the status parameter options).

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 zero waste: first establishes action and workflow timing, second details return content. Every word earns its place; front-loaded with imperative action 'Check' followed by critical workflow constraint.

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 presence of an output schema and 100% parameter coverage, the description appropriately focuses on high-level return value summary ('what broke, workarounds, resolution status') rather than detailed field documentation. Covers data provenance which is critical for a 'problems' knowledge base.

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

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

With 100% schema description coverage, the schema adequately documents all parameters (slug, limit, status). The description implicitly references the 'entity' parameter but does not add syntax, format details, or semantic meaning beyond what the schema already provides, warranting the baseline score.

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 specific verb 'Check' with resource 'known issues' and explicitly scopes the tool to investigating entity problems. The phrase 'BEFORE recommending it' effectively distinguishes this from sibling 'nanmesh.entity.recommend' by establishing workflow precedence.

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 temporal guidance on when to use ('BEFORE recommending it'), establishing clear workflow context. However, it lacks explicit 'when-not-to-use' statements or direct references to alternatives like 'use entity.get for basic entity information instead.'

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

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

While annotations declare readOnlyHint=true, the description adds substantial behavioral value by disclosing the exact ranking algorithm weights (trust reviews 70%, recency 15%, etc.). This transparency about HOW results are ordered is critical for agent expectations.

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 with zero waste. First sentence delivers purpose and usage trigger; second sentence provides unique ranking methodology detail. Front-loaded action verb with no 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?

Given 100% schema coverage, present annotations (readOnlyHint), and existence of output schema, the description is appropriately complete. The ranking algorithm disclosure compensates for not detailing return values. Could marginally improve by contrasting with 'entity.search' or 'trust.rank' siblings.

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 detailed field descriptions already present. The description provides conceptual mapping ('use case or category' aligns to 'query' and 'category' params) but does not add syntax, format, or constraint 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?

Description uses specific verb 'Get' with clear resource 'trust-ranked recommendations'. The phrase 'trust-ranked' effectively distinguishes from sibling 'entity.search' (general search) and 'trust.rank' (raw ranking), while targeting 'use case or category' scopes aligns with the parameter 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?

Provides explicit trigger phrase 'what should I use for X?' which clearly signals when to invoke. Lacks explicit 'when not to use' or comparison to alternatives like 'entity.search' or 'entity.compare', but the use-case framing is specific enough for selection.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false (safe, closed-world search). Description adds valuable behavioral context about return payload: specifically lists 'trust_score (agent consensus), community_score, and open problem counts', helping the agent anticipate result structure 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?

Three sentences, zero waste: (1) purpose + value prop, (2) critical usage guideline, (3) output preview. Front-loaded with action verb and precisely scoped. No redundant or vague 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?

Appropriately complete for a search tool with existing output schema. Description previews key return fields (trust_score, community_score, problems) which aids agent interpretation. Could optionally mention search fuzziness/pagination, but sufficient given schema richness and domain clarity.

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 detailed descriptions for all 3 parameters (q, limit, entity_type). Description mentions 'Search for...' implying the query parameter but adds no syntax details, format constraints, or usage examples beyond the schema. Baseline 3 appropriate for high-coverage schemas.

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?

Excellent specificity: verb 'Search' + resource 'software tools, APIs, and dev products' + unique differentiator 'trust scores from real AI agent experiences'. Clearly distinguishes from sibling 'get' (by ID) and 'recommend' (algorithmic suggestion vs. 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?

Strong explicit guidance: 'Use this BEFORE recommending any tool' establishes clear workflow precedence relative to sibling 'nanmesh.entity.recommend'. Missing explicit 'when-not' (e.g., avoid when exact entity ID known) and doesn't name alternatives directly, but provides clear temporal context.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false. Description adds valuable context by specifying exactly what data points are retrieved (total entities, registered agents, reviews cast, categories) beyond generic 'stats'. Does not mention rate limits or caching, but sufficient for tool complexity.

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 efficient sentence front-loaded with action verb. Lists four specific metrics with zero redundancy. Every word earns its place; no filler or redundant explanation given the simplicity of the 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?

Appropriate for tool complexity. Input schema requires no explanation (no params). Output schema exists (not shown), so description needn't detail return format. Listing specific metrics covered provides sufficient context for an agent to determine if this meets their information needs.

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?

Zero parameters present. Per rubric, 0 params = baseline 4. Schema is empty object with 100% coverage (trivially complete). Description appropriately focuses on return value semantics rather than inventing parameter documentation.

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

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

Description uses specific verb 'Get' with clear resource 'NaN Mesh network health' and enumerates exact metrics returned (entities, agents, reviews, categories). Distinct from sibling tools which operate on specific agents/entities/trust relationships rather than platform-wide aggregates.

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 when-to-use guidance or comparison to alternatives (e.g., vs entity.get for specific details). However, the specific metrics listed and 'network health' phrasing imply platform-wide usage context. Adequate but not explicit.

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; description adds crucial behavioral context including authentication requirements ('no key'), weight system ('0.1x weight'), and comparative impact vs. sibling tool. 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?

Four sentences with zero waste. Front-loaded with key constraints ('no registration'), followed by usage guidance, behavioral traits (weight), and alternatives. Every sentence earns its place.

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

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

Given output schema exists (per context signals) and annotations are present, description comprehensively covers purpose, auth requirements, weight semantics, and sibling relationships. No gaps for this complexity level.

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% providing baseline documentation. Description adds semantic meaning beyond schema by mapping 'direction' to trust concepts ('up' for trust, 'down' for distrust) rather than just numeric values, and emphasizes the 'slug + direction' contract.

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?

Specific verb+resource ('express trust/distrust'), clear scope ('community signal'), and explicit differentiation from sibling nanmesh.trust.review via weight comparison (0.1x vs 10x).

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

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

Explicit when-to-use ('Use when you want to quickly express...'), clear prerequisites ('no registration, no key'), and names specific alternative tool ('use nanmesh.trust.review instead').

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

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

Annotations already declare readOnlyHint=true, confirming safe read behavior. The description adds valuable context about the specific data returned (score, rank position, review breakdown) beyond what annotations provide. However, it omits behavioral details like error handling for non-existent entities or caching behavior.

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

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

The description consists of exactly two sentences with zero redundancy. The first sentence defines functionality and return values; the second provides usage context. Every word earns its place with no filler or tautology.

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 presence of an output schema (which obviates the need for detailed return value documentation), 100% parameter coverage, and read-only annotations, the description successfully covers purpose, usage timing, and high-level return structure. It could improve by mentioning error states or trust score interpretation.

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

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

With 100% schema description coverage, the input parameter 'slug' is fully documented in the schema itself ('Entity slug or UUID'). The description references 'entity' which aligns with the parameter but does not add substantial semantic meaning beyond the schema's own documentation, warranting the baseline score for high-coverage schemas.

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 specific verbs ('Check') and identifies the exact resource (entity's trust reputation) and outputs (score, rank position, review breakdown). It clearly distinguishes this lookup tool from sibling mutation tools like nanmesh.trust.report_outcome and nanmesh.trust.review by specifying it retrieves rather than writes 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 second sentence provides clear contextual guidance ('Use to verify credibility before recommending'), establishing when this tool should be invoked in a workflow. However, it does not explicitly name alternative tools (e.g., when to use entity.get vs trust.rank) or specify exclusion criteria.

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) but provide no behavioral details. The description adds critical context that the call 'Automatically becomes a +1 or -1 review', disclosing the side effect of writing to the trust system and the specific scoring normalization applied. It does not, however, clarify idempotency or aggregation behavior if called multiple times for the same entity.

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 tightly constructed sentences with zero redundancy. Front-loads value proposition ('Simplest way to contribute'), immediately clarifies mechanism ('just say if a tool worked or not'), and ends with critical temporal constraint ('Use AFTER'). Every word earns its place; no generic fluff or tautology.

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 narrow scope (binary outcome reporting) and the existence of an output schema, the description adequately covers the essential behavioral contract. It explains the trust system integration (+1/-1 conversion) and auth context (via `agent_key` parameter reference to 'nmk_live_'). Could marginally improve by noting whether duplicate reports overwrite or aggregate, but sufficient 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?

With 100% schema description coverage, the baseline is 3. The description adds value by synthesizing the abstract schema fields (`entity_id`, `worked`) into cohesive domain language ('tool worked or not', 'tried or recommended something'). This narrative framing helps the agent understand that `entity_id` refers to the tested tool and `worked` captures the binary success state, bridging the gap between technical parameter names and user intent.

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 action verb pair ('contribute' via reporting) and clarifies the resource ('if a tool worked or not'). It distinguishes from sibling trust tools (review, rank, favor) by positioning this as the 'Simplest way' with a binary outcome that 'Automatically becomes a +1 or -1 review', clearly signaling its lightweight, post-hoc feedback purpose compared to more complex review mechanisms.

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 temporal guidance: 'Use AFTER you tried or recommended something and know the outcome.' This clearly delineates when to invoke this tool versus alternatives like `nanmesh.entity.recommend` (likely used before/at recommendation time) or `nanmesh.trust.review` (potentially for detailed asynchronous feedback), preventing misuse as a predictive rather than outcome-reporting mechanism.

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 declare readOnlyHint=false. The description adds valuable behavioral context: ranking weight ('70% of ranking'), idempotency semantics ('overwrites previous'), and authentication requirements. Does not contradict annotations. Could be improved by mentioning error conditions or rate limits.

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?

Five sentences, each earning its place: purpose, timing, system impact, constraint, and auth/alternative. Information is front-loaded with the core action, followed by operational constraints. No redundant or filler text.

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 presence of an output schema (not shown but indicated), the description appropriately focuses on invocation prerequisites and workflow context rather than return values. Covers authentication, alternatives, and mutation semantics sufficiently for a tool of this complexity.

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%, establishing a baseline of 3. The description highlights key parameters ('Requires agent_key', '+1 or -1') but does not add semantic depth beyond what the schema already provides (e.g., no examples, format details, or validation rules not in schema).

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

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

The description clearly states the specific action ('Cast your expert +1 or -1 review') and target resource ('any entity'). It distinguishes itself from sibling tools by contrasting with 'nanmesh.trust.favor' (auth vs. no-auth) and implying its role in the evaluation workflow.

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 temporal guidance ('Use AFTER evaluating'), prerequisites ('Requires agent_key'), constraints ('One review per agent per entity'), and directly names the alternative tool ('use nanmesh.trust.favor instead'). This is exemplary guidance for agent decision-making.

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