Mnemom — Trust Ratings for AI Agents

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

Annotations already indicate this is not read-only and not idempotent. The description adds valuable context: 'No human in the loop' and 'provably yours' suggest a non-reversible, automatic binding that creates a persistent ownership record. This goes beyond what annotations provide, though it doesn't fully disclose edge cases like conflict resolution.

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 action, and every sentence adds value. There is no redundancy or filler, making it optimally 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?

Given the presence of an output schema, 100% parameter coverage, and annotations, the description is fairly complete. It covers the purpose and key behavioral trait ('No human in the loop') but could ideally mention what happens post-claim (e.g., immutability) for full completeness. Still, for the complexity level, 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?

Schema description coverage is 100%, with all three parameters (org_id, agent_id, hash_proof) already clearly documented. The description does not add any additional parameter-level semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Claim a verifiable identity — bind an agent to your organization') with a specific verb and resource, and distinguishes itself from siblings like verify_agent_binding by emphasizing the binding/claiming action rather than verification.

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 clear context for use ('bind an agent to your organization') and mentions the automated nature ('No human in the loop'), which implies when this tool is appropriate. However, it does not explicitly mention alternatives or when-not-to-use, so it does not earn a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is covered. The description adds that the lookup targets 'public identity and trust state,' providing some scope beyond annotations, but it does not disclose behavior for missing IDs, error cases, or data freshness, so the added transparency is modest.

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, front-loaded sentence with no wasted words. It names the action, the resource, and the lookup key, while the final clause adds meaningful context about the tool's reliability as an 'accountable record.'

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 one-parameter lookup with an output schema and strong annotations, the description is largely complete: it identifies what is looked up and why it matters. The only missing piece is explicit guidance about when to prefer sibling tools, but that is more a usage-guideline concern and does not undermine overall completeness for a simple read-only lookup.

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

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

The input schema has 100% coverage: agent_id is described with an example ('e.g. smolt-abc123'). The description only repeats 'by ID' without adding new parameter semantics, 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?

The description states a specific verb and resource: 'Look up an agent's public identity and trust state by ID.' This clearly distinguishes it from siblings like list_agents (which lists) and get_reputation (which focuses on reputation), and it explicitly identifies the lookup key (ID).

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 one needs the accountable agent record, but it provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternative tools like get_reputation or verify_agent_binding. It relies on context rather than explicit 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 already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds that it's 'computed from the agent's own verified activity record' and clarifies the visibility field distinction, providing useful behavioral context beyond annotations.

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

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

Two concise, front-loaded sentences with no wasted words. Each sentence adds value: main action, result, and key properties. Perfectly sized for quick comprehension.

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?

Tool has output schema, so return values are covered. Description provides enough context about the rating's nature, visibility, and computation. Minor gap: does not mention if the rating is numeric or categorical, but output schema handles this.

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 adequate description for agent_id (example format). Description does not add extra parameter meaning beyond the 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?

Clearly states 'Look up an AI agent's published Trust Rating' with specific verb and resource. Distinguishes from siblings like get_reputation_badge by mentioning 'returns the rating plus the technical factors', but does not explicitly contrast with other similar siblings like scan_trust.

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 context that it's 'Free, public, read-only', implying when to use (simple lookup). No explicit guidance on when not to use or alternatives like search_reputation_directory or verify_reputation, leaving some 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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds output format details (URL, snippets) but does not disclose additional behavioral traits like authentication requirements or rate limits beyond what annotations imply.

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

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

A single, front-loaded sentence that conveys all necessary information without extraneous words. Every part contributes to understanding the tool's purpose and output.

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

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

Given the tool's simplicity (one parameter, clear output schema), the description fully covers what the tool does and returns. No additional context is needed for an agent to correctly invoke it.

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

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

Schema coverage is 100% with a clear description for the single parameter 'agent_id'. The tool description does not add meaning beyond the schema, meeting the baseline 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 clearly states the tool returns an embeddable Trust Rating badge, specifying the output includes badge URL and Markdown/HTML snippets. The verb 'Get' and resource 'badge' are specific, and it distinguishes from sibling tools like 'get_reputation' which likely return raw data.

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

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

The description implies usage when an embeddable badge is needed but does not explicitly state when to use this tool versus alternatives (e.g., 'get_reputation' for raw data). No guidance on when not to use it 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, idempotentHint, and no destructive action. The description adds key behavioral details: zero authentication required, no required arguments, and the optional token parameter behavior for returning a token-gated manifest.

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, dense with information, but remains clear. It front-loads the key idea ('Zero-auth, no-args orientation') and packs details 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?

Given the tool's simplicity and the presence of an output schema, the description covers all necessary context: purpose, authentication needs, optional parameters, and content returned.

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%; the description adds essential meaning by explaining the token parameter's purpose and effect, which the schema description only briefly mentions as 'Optional Dojo try-me invite token'.

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 provides a zero-auth orientation including system identity, map, authentication, and recommended tools like scan_trust. It distinctly sets itself apart from sibling tools by being a no-args, no-auth entry point.

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 mentions 'Zero-auth, no-args' suggesting use for initial orientation with no prerequisites. It implies when to use it but does not explicitly state when not to use or provide direct alternatives among 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the scope constraint ('owned by the authenticated user') and pagination support, which is helpful. However, it does not disclose ordering, error cases, or rate limits, so it only moderately adds beyond annotations.

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

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

Two sentences, front-loaded with the action and resource, then a clarifying detail. Every word earns its place; there is no fluff or redundancy. The dash separator improves readability.

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 high annotation coverage, a fully described input schema, and an existing output schema, the description is complete for a simple read-only list operation. It correctly mentions pagination and the ownership scoping, which are the only non-obvious aspects beyond the structured data.

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%, with both limit and offset parameters already fully described in the schema. The tool description only says 'Supports pagination,' which adds no additional meaning beyond the schema. Baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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

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

Description uses a specific verb and resource: 'List your agents — List all agents owned by the authenticated user.' It clearly distinguishes from sibling tools like get_agent (which fetches a single agent) and claim_agent (which assigns ownership). The scope is explicit and 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 states it lists agents owned by the authenticated user and supports pagination, providing clear context for when to use this tool. It does not explicitly name alternatives or exclusions, but the sibling list hints at differentiated use cases. A stronger statement like 'use this instead of get_agent for all agents' would earn a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this with 'No DB writes' while adding that it composes against a hypothetical body and returns conflicts and a composed view. This adds useful context beyond annotations, though the meaning of 'cascade' and 'agent layer' could be clearer.

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 purpose and dry-run nature, with no wasted words. It efficiently conveys the primary function, side effects, and intended usage.

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

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

Given the tool's complexity (8 nested params, output schema exists), the description provides sufficient orientation: what it does, side effects, and typical use case. It does not elaborate on input semantics, but the schema covers that, and the output schema eliminates the need to describe return structure.

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

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

Schema description coverage is 100%, so the schema fully documents all eight parameters. The description does not add parameter-specific meaning, but the rich schema already handles that, 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?

The description clearly states the tool performs a dry-run preview of composed alignment at the agent layer, returning conflicts and the composed view. It differentiates from sibling tools like put_alignment_by_agent (write) and preview_compose_protection_by_agent (protection vs alignment).

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 specifies it is a dry run with no DB writes and mentions its use by the dashboard editor for live conflict markers, implying a preview-before-commit context. It does not explicitly contrast against put_alignment_by_agent, but the use case is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: it explains the tool performs a dry run against a hypothetical body, returns conflicts plus the composed view, and explicitly confirms no database writes. This aligns with annotations and enriches understanding without contradicting them.

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

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

The description is two sentences, front-loaded with the core purpose ('Preview composed protection (dry run)') and immediately conveys key traits ('No DB writes', returns conflicts + composed view, dashboard editor use). Every word earns its place with no redundancy.

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

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

Given the tool's complexity (7 params, nested objects, output schema), the description covers the high-level behavior, safety profile, and intended usage. It does not need to explain return values because an output schema exists. It could have elaborated on what a 'hypothetical body' is, but the annotations, schema, and output schema collectively fill the gaps, making it sufficiently complete 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 description coverage is 100%, so the baseline is 3. The description does not add specific parameter-level semantics beyond what the schema provides, and it does mention 'hypothetical body' but does not map that to individual parameters. However, the schema descriptions are already rich, so no significant gap exists.

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

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

The description uses a specific verb ('Preview composed protection (dry run)') and resource ('protection'), and clearly states the tool composes the cascade against a hypothetical body and returns conflicts + composed view. It also distinguishes itself from siblings by emphasizing 'No DB writes' and the dashboard editor use case, differentiating it from preview_compose_alignment_by_agent and put_protection_by_agent.

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 specifies a clear use case: 'Used by the dashboard editor for live conflict markers.' It also implies a dry-run/no-persistence context with 'No DB writes,' which suggests when not to use it (i.e., when persistence is needed), though it does not explicitly name put_protection_by_agent as the alternative. This is clear context but lacks explicit 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?

The description adds meaningful behavioral context beyond annotations: it discloses server-side composition merging across the platform→org→team→agent cascade, writes the canonical composed card, and requires Idempotency-Key. Annotations already signal destructive and idempotent behavior, and the description reinforces and extends this without contradiction.

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

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

The description is front-loaded with the purpose but becomes a run-on sentence and ends abruptly with "Honor...", which appears truncated. While each segment carries useful information, the structure suffers from the incomplete final clause and the dense single-sentence 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?

Given the tool's complexity (8 params, nested objects) and rich schema plus output schema, the description covers key behavioral aspects: media types, merge cascade, canonical card, and idempotency requirement. It misses explicit return-value discussion (covered by output schema) and the truncated "Honor..." likely indicates more context, but it is still fairly complete.

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

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

Schema description coverage is 100%, so the schema fully explains all parameters. The description adds only a high-level note that the body is the full UnifiedAlignmentCard, but does not enrich individual parameter semantics beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the verb and resource: "Publish or replace the alignment manifest". It distinguishes from siblings like put_protection_by_agent (protection card) and preview_compose_alignment_by_agent (preview), making its specific purpose unmistakable.

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

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

The context is clear: this is the publish/replace operation for an alignment card, accepting YAML or JSON with a full UnifiedAlignmentCard body. However, it does not explicitly mention alternatives like preview_compose_alignment_by_agent or state when not to use it, so it lacks explicit 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?

The description adds meaningful behavioral context beyond annotations: it specifies accepted input formats (YAML/JSON), requires the full UnifiedProtectionCard, explains the server-side merge across platform→org→team→agent cascade, and mentions the Idempotency-Key requirement. This complements the annotations (destructiveHint, idempotentHint) without contradicting them, though the truncated ending leaves some details unstated.

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 dense sentence that front-loads the core action ('Publish or replace') and then efficiently packs key details: formats, body requirement, composition behavior, and idempotency requirement. It is appropriately concise for the complexity, though the truncated 'Hon...' leaves an incomplete thought and the sentence is slightly overloaded.

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 high complexity (7 parameters, nested objects, output schema), the description covers essential aspects: purpose, input format, body structure, composition semantics, and idempotency requirement. The output schema handles return-value documentation. Missing details like error cases or permission requirements are not expected at this level, but a bit more explicit guidance on usage vs alternatives would strengthen it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds high-level context (body is the full card, composed server-side), but does not detail individual parameters beyond what the schema already provides. It adequately reinforces the 'full card' notion but does not deeply enhance parameter-level understanding.

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

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

The description uses a specific verb+resource pair ('Publish or replace the protection manifest') and clearly distinguishes itself from sibling tools like preview_compose_protection_by_agent (which previews instead of writing) and put_alignment_by_agent (which handles alignment, not protection). It also explains the composition cascade, making the tool's responsibility 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 implies when to use it: it is the write path for protection cards, as opposed to preview_* siblings. However, it does not explicitly state 'use this instead of preview' or list any exclusions or alternative conditions. The guidance is inferred from tool names and the description's wording, not explicitly stated.

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 this is a write operation (readOnlyHint=false) and not idempotent or destructive. The description adds the intended effect of improving detection accuracy but does not disclose side effects such as persistence on a governance card or visibility to the organization; that detail is deferred to the schema's summary parameter description.

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, front-loaded sentence that states the action, target, and purpose without redundancy. Every phrase earns its place, and it is appropriately sized for the tool's complexity.

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, combined with a fully covered input schema and an output schema, provides enough context for an agent to select and invoke the tool. It lacks an explicit 'when not to use' statement or mention of the governance-card storage detail, but those are not required given the structured schema information.

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%, with parameter descriptions already explaining `type`, `summary` constraints, and identifier formats. The main description adds little beyond the domain context of a 'recipe' being an automated detection rule, so it does not need to compensate significantly.

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

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

The description uses a specific verb ('Submit') and a specific resource ('false-positive / false-negative correction for one of Mnemom's automated detection rules (a 'recipe')'). It clearly distinguishes this tool from the sibling list, which contains no other submission/report tool.

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

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

The description gives clear context: this is for submitting technical feedback that improves detection accuracy, analogous to a bug report against a spam filter. It does not name explicit alternatives or exclusions, but no sibling appears to offer a similar reporting function, so the usage 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds significant behavioral details: results are cached for 24h, the `fresh` parameter bypasses cache but is rate-limited, it proxies to an SSRF-locked scanner, and preserves Ed25519 signature and permalink. There is no contradiction with annotations.

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

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

The description is concise with 4-5 sentences, each serving a distinct purpose: core action, caching behavior, forced re-scan, proxy details, and a link to docs. There is no fluff, and the most critical information is front-loaded.

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

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

Given the existence of an output schema (not shown), the description does not need to detail return values. It mentions result fields (cached, scannedAt), signature preservation, permalink, and a link to rubric docs. It also covers caching, rate limiting, and zero-auth. This provides a comprehensive understanding of the tool's behavior and output.

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

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

Schema coverage is 100% with basic descriptions for `url` and `fresh`. The description adds context: `fresh` is 'equivalent to the scanner's rescan flag' and explains caching implications. This adds value beyond the schema, raising the score above baseline 3.

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

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

The description clearly states the tool scans a website's agent-trust-readiness and returns a signed scorecard, specifying the verb 'scan' and resource 'website's agent-trust-readiness'. This distinguishes it from sibling tools like claim_agent, get_reputation, etc., which focus on agents and reputation rather than website scanning.

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

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

The description provides clear context: zero-auth, caching behavior, and the option to force a fresh scan with the `fresh` parameter. It implicitly tells when to use this tool (when you need a trust-readiness scan) but does not explicitly mention when not to use it or name alternatives. The sibling list contains verify_scan, which might be related, but no exclusion 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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds key behavioral info: the tool only searches agents with public reputation visibility, requires zero authentication, and returns agent_ids. No contradiction with annotations.

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

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

Two sentences, front-loaded with core action, followed by usage guidance. No redundant words. Every sentence earns its place.

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

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

Covers purpose, scope (public directory), auth requirement, and next steps. With an output schema present, the description doesn't need to detail return format. Minor gap: does not explicitly state that results are paginated, but schema covers pagination params. Overall good 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?

All 6 parameters have descriptions in the schema (100% coverage), so the description adds no new param-level detail. It provides context for the 'q' parameter ('name or id-prefix') but that is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Resolve an agent name or id-prefix to a real agent_id over the PUBLIC reputation directory', using a specific verb and resource. It distinguishes from siblings like get_agent (requires id) and list_agents (different scope), and positions itself as the entry point for discovering agent IDs.

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 tells when to use this tool: as the entry point to discover a concrete agent_id, then delegate to get_reputation/verify_reputation. It also notes 'zero-auth', setting expectations. This provides clear guidance on alternatives and preconditions.

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, idempotentHint=true, destructiveHint=false. The description adds behavioral details: it returns a Merkle-root + hash-chain attestation and a pointer to the integrity certificate. It also clarifies that it does NOT perform an Ed25519 check. 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, front-loaded with the main action and outputs, and contains no superfluous information. Every sentence adds value.

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

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

Given the tool has an output schema, good annotations, and only one parameter, the description fully addresses the return values and behavioral context. It is complete for an AI agent to understand invocation and 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?

Schema description coverage is 100% and the lone parameter (agent_id) is already described in the schema. The description does not add additional meaning or constraints beyond what is in 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 verb 'Attest' and the resource 'agent's Trust Rating', and distinguishes itself from 'verify_scan' by specifying the type of attestation (chain-integrity vs. Ed25519 signature check). This provides a specific and unambiguous purpose.

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

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

The description explicitly tells when to use this tool (to verify chain integrity) and when not (for Ed25519 check, use verify_scan). This provides clear guidance on tool selection among siblings.

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

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

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds valuable context beyond annotations: 'Zero-auth', the return shape {verified, key_id, canonicalization}, and that verification uses the public key at mnemom://iitr/jwks. This clarifies auth needs and output without contradicting the safety hints.

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

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

The description is compact (two sentences) yet rich with necessary information: purpose, input modes, return shape, key origin, and spec links. Every element earns its place with no redundancy or fluff.

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

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

Despite the tool's complexity (nested scan object, oneOf constraint, output schema), the description covers the essential workflow: how to pass input, what verification is performed, the return value, and where to find detailed specifications. The output schema handles return details, so the description need not repeat them.

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

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

Schema description coverage is 100%, so the schema fully documents the two parameters, including their types and relationships (oneOf). The description adds a slight clarification that `url` triggers a re-scan, but the schema already states this. No significant additional parameter semantics are provided beyond the structured fields.

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 verifies a website scan scorecard's Ed25519 signature, distinguishing it from scan_trust (which creates the scorecard) and other verify tools (verify_reputation, verify_agent_binding). The phrase 'IN-BAND (verify, don't trust)' adds specific method and intent.

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

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

It explicitly says to pass either a `scan` from scan_trust or a `url` to re-scan, providing clear input guidance. It does not name specific sibling alternatives or exclusions, but the reference to scan_trust and 'verify, don't trust' implies when to use this tool over blindly accepting a scorecard.

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