Neotoma

Overview Schema Related Servers Score Discussions

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.21.0
Disambiguation2/5
Many tools have overlapping purposes, such as retrieve_entities, retrieve_entity_by_identifier, retrieve_entity_snapshot, retrieve_related_entities, and retrieve_graph_neighborhood, which all return entity data with subtle differences. Identity resolution tools (merge_entities, split_entity, list_potential_duplicates, identify_entity_by_signals) also blur boundaries, making misselection likely without deep parameter inspection.
Naming Consistency3/5
Most tools follow a verb_noun pattern (list_observations, create_relationship, delete_entity), but verbs are not standardized: get, list, retrieve, describe, submit, and sync are used interchangeably. A few outliers like npm_check_update, neotoma_turn_summary, and manage_bundles deviate from the pattern, reducing overall consistency.
Tool Count2/5
With 62 tools, the surface is far too large for an agent to efficiently navigate, even for a knowledge graph server with broad capabilities. Many tools are specialized (e.g., health_check_snapshots, npm_check_update, neotoma_turn_summary), and the count exceeds what is reasonable for typical MCP usage.
Completeness4/5
The tool set covers the full lifecycle of entities, relationships, schemas, and interpretations, plus sync, subscriptions, and issue management. Minor gaps exist (e.g., no direct entity update tool, resolve_sync_conflict is a stub, no list_sources), but agents can work around these with store/correct and other existing tools.
Average 3.7/5 across 62 of 62 tools scored. Lowest: 1.1/5.
See the Tool Scores section below for per-tool breakdowns.
- 14 of 14 community issues answered or closed in the last 6 months
- 525 commits in the last 12 weeks
- Last stable release on July 30, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description gives no behavioral information such as side effects, permissions, or success/failure conditions. 'Stub' implies the tool may not be functional, which is a critical behavioral trait left unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short but not effectively concise—it omits essential information. 'Stub' indicates a placeholder, and the instruction to use an alternative tool suggests this description is not final.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is grossly incomplete. It fails to explain what the tool does, when to use it, or what the parameters mean.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only sender_peer_url and guest_access_token have descriptions). The description adds no meaning to parameters; it does not explain entity_id, strategy enum values, or how they interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Stub; use correct on the entity for manual resolution today.' does not state what the tool does. 'Stub' implies it's incomplete or non-functional, and the reference to 'correct' confuses the purpose. No specific verb or resource is described.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The mention of 'use correct on the entity' suggests an alternative but provides no context or conditions for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility. It fails to disclose pagination, default parameter behavior, or error responses, leaving agent uninformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but it omits critical details and does not earn its place by being informative. It is under-specified rather than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, the description is woefully incomplete. An agent cannot determine proper usage, pagination, or what constitutes an observation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (40%), but description adds no parameter information. The phrase 'for a given entity' suggests entity_id is needed, but the schema marks it not required, creating confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List all observations for a given entity', which identifies the resource and action. However, it does not differentiate from sibling list tools (e.g., list_interpretations, list_peers) and is ambiguous about whether entity_id is required.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives. Among many list tools in the sibling list, the description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'POST' implying mutation, but does not disclose whether the operation is destructive, idempotent, or what side effects occur. The behavior beyond sending a request is opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, efficient and front-loaded with 'Bounded outbound peer sync'. However, it packs technical details (POST path, env vars) without punctuation or structure, making it somewhat cryptic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters and no output schema, the description omits critical details: success/failure behavior, response format, how 'limit' affects execution, and what 'observations' are synced. It is not sufficiently complete for an agent to use without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 50% coverage (peer_id lacks description). The description mentions 'peer sync_target_user_id' but the schema only has peer_id, causing confusion. It adds little meaning beyond the schema: it says limit is optional, but the schema already has a minimum/maximum/description. The description fails to clarify the role of peer_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it performs 'bounded outbound peer sync' via POST to a webhook for observations, which gives a specific verb and resource. However, it doesn't clearly distinguish from sibling sync tools like 'sync_entity_submissions' or 'sync_issues', and the jargon may be unclear to an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists prerequisites (environment variables, peer sync_target_user_id) and mentions an optional limit, but provides no guidance on when to use this tool versus alternatives. There is no explicit when/when-not or contrast with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description states it lists runs for the authenticated user with optional source_id filter, but lacks details on authentication requirements, side effects, rate limits, or handling of empty results. The description is too brief to compensate for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence, but it lacks detail. It is not wasteful, but the brevity sacrifices informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without output schema or annotation support, the description is critically incomplete. It omits pagination details (limit/offset), the meaning of user_id, and what an interpretation run entails, leaving the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 4 parameters (user_id, source_id, limit, offset) with 0% coverage in schema descriptions. The description only mentions source_id as an optional filter, adding no meaning for user_id, limit, or offset.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (interpretation runs) with authentication scope and optional filtering. However, it does not distinguish from any close sibling tools, as there is no other list-interpretations tool among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this vs. alternatives. It mentions optional filtering but does not specify when not to use or prerequisites. No contrast with create_interpretation or other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds 'recent' implying ordering but does not clarify ordering criteria or pagination behavior. Annotations already declare readOnlyHint=true, so minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, but omits important details about parameters and behavior. Conciseness should not come at cost of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should indicate return structure. Does not mention pagination, ordering, or what 'recent entities' includes. Incomplete for a list tool with pagination parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 'entity_type' is implicitly explained as the filter. 'limit' and 'offset' are not described despite being crucial for pagination. Schema description coverage is 0%, so description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'list', resource 'entities', filter by 'entity_type', and scope 'for the authenticated user'. It distinguishes from sibling 'list_entity_types' but not from similar list tools like 'retrieve_entities'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'retrieve_entities' or 'submit_entity'. No when-not-to-use or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavior. It states 'Deactivate a peer' but does not clarify whether the action is reversible, what happens to associated data, or any authentication requirements. With zero annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence) and to the point. However, brevity comes at the cost of missing important details. It is not verbose, but could be improved slightly without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (1 param, no output schema), the description is minimally acceptable but lacks behavioral context. It does not explain return values, side effects, or any error conditions. For a deactivation operation, more completeness is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'peer_id' with 0% description coverage. The description merely repeats the parameter name ('by peer_id') without adding any semantic detail about format, constraints, or examples. The schema provides only a type string, leaving the agent with minimal understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Deactivate a peer') and the required input ('by peer_id'). It is specific enough to understand the tool's purpose, though it does not explicitly differentiate from sibling tools like 'sync_peer' or 'add_peer'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'add_peer' or 'sync_peer'). The description does not specify prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full weight, but it only states 'Create' without disclosing error handling, validation, batch size limits, or return values. The description is too brief for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is short and front-loaded, but conciseness comes at the expense of missing critical details. It is not optimally balanced.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (batch operation with nested objects, enum types) and lack of annotations or output schema, the description is insufficient. It omits nearly all behavioral and contextual detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no information about parameters like relationships array structure, source_id, or user_id. Meaningful parameter guidance is entirely absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Create', the resource 'typed relationships between existing entities', and the scope 'in one batch'. This clearly distinguishes it from the singleton sibling 'create_relationship'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., create_relationship for single relationships), nor are there any prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to disclose behavioral traits such as read-only nature, authentication needs, or what 'provenance chain' implies; merely states the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but overly brief; it gets the point across but could benefit from additional detail without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description is incomplete; it does not explain what the provenance chain contains or the return format, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the two parameters (entity_id, field) beyond their names, leaving ambiguity about valid values and usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and the specific resource 'provenance chain for a specific field in an entity snapshot', distinguishing it from siblings like retrieve_entity_snapshot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any mention of exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It fails to mention that the tool likely requires the file to already exist, whether it modifies anything, or if it returns a URL string. The term 'signed' implies authentication needs but is not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence conveying the core function with no unnecessary words. Highly efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is too brief. It omits key details like return type, error scenarios, prerequisites (file existence), and any side effects. The agent cannot reliably use this tool without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage. The description does not explain the parameters' meanings beyond their names. For expires_in, units and default are missing; file_path format is not clarified. The description adds little semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Retrieve) and resource (a signed URL for accessing a file), which distinguishes it from siblings like parse_file (reads content) or store (uploads). However, it does not explicitly clarify whether the URL is temporary or scoped to the current user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any prerequisites or limitations. The description only states the function without contextual cues about scenarios (e.g., file must exist, requires authentication).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full responsibility but only hints at the registration process. It incorrectly implies only bidirectional sync while the schema includes push and pull. No mention of side effects, auth requirements, or post-registration behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. However, for an 11-parameter tool, it is under-specified and could benefit from a brief list of required fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high complexity (11 params, no output schema, no annotations), the description is insufficient. It does not explain the peer_config concept, expected return, or follow-up actions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 27%. The description adds meaning for peer_url, entity_types, and shared_secret but omits 8 of 11 parameters, including required ones like peer_id, direction, and auth_method.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Register' and the resource 'Neotoma peer', and mentions key aspects like peer_url, entity_types allowlist, and shared_secret. It distinguishes the tool from siblings such as remove_peer and sync_peer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like sync_peer or remove_peer. It does not specify prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It only mentions that observations are linked to source_id and interpretation_id. It does not disclose potential destructive behavior, error conditions, or side effects. The transparency is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences. The first sentence states the purpose, the second gives an alternative usage. There is no unnecessary information. It could be slightly improved with structured formatting, but it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters (including nested objects), no output schema, and no annotations, the description is too brief. It does not explain the relationships parameter, interpretation_config, idempotency_key, or return value. It also does not clarify how this tool differs from siblings like store or create_relationship. Incomplete for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, so the description should compensate. It adds the context 'agent-extracted flat entities' implying the entities parameter structure, but does not elaborate on source_id, relationships, idempotency_key, or user_id. The added meaning is limited.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create', the resource 'interpretation row', and the context 'from agent-extracted flat entities for an existing source'. It also notes that observations are linked to both source_id and interpretation_id. However, it does not distinguish from siblings like create_relationship, which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a guideline: use 'store' with an interpretation block when batching. This hints at when to use an alternative, but it does not explicitly state when NOT to use this tool or mention prerequisites like the source existing. The guidance is present but not comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavior. 'Deactivate' implies a state change but lacks details on effects, irreversibility, or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks necessary detail for an effective description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal description, the tool lacks completeness. Return values, side effects, and usage notes are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only repeats the parameter name without adding format, source, or validation details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'deactivate' and the resource 'subscription', distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Sibling 'subscribe' exists but no comparison or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden, but it only says 'register,' implying a write operation without detailing side effects like overwrite behavior, permission requirements, or activation semantics (despite an 'activate' parameter). This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences with no fluff. Every word adds information, though the total information provided is limited.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, 3 required, nested objects, and no annotations or output schema, the description is inadequate. It does not cover essential parameters or usage nuances, leaving an agent to guess how to structure schema_definition or reducer_config.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43%, and the description does not explain any parameters by name. The only hint is 'global and user-specific schemas,' which roughly maps to user_specific and user_id, but it does not clarify required parameters like entity_type, schema_definition, or reducer_config.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Register' and identifies the resource as 'a new schema or schema version,' with a clear note about global and user-specific schemas. This distinguishes it from sibling tools like update_schema_incremental or analyze_schema_candidates. The only minor ambiguity is how versioning works, but the core purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for registering new schemas when none exists or a new version is needed, but it does not explicitly state when to prefer this over update_schema_incremental or other schema-related tools. Mentioning global vs user-specific schemas hints at selection criteria, but no exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions 'snapshot' and 'provenance' but does not clarify read-only nature, permission requirements, or side effects. Minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and object, no redundant words. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 3 required parameters and an enum, the description does not explain the shape of the snapshot or how provenance is represented. Without an output schema, more detail is needed for an agent to understand what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions. The tool description adds only 'with provenance' which is not parameter-specific. Baseline of 3 is appropriate as schema already documents parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get), object (snapshot of a specific relationship), and includes relevant detail (with provenance). It distinguishes from sibling tools like list_relationships and retrieve_entity_snapshot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like list_relationships or retrieve_entity_snapshot. The description does not mention any prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description bears full burden. It implies a read operation but doesn't confirm safety, side effects, or response behavior. No mention of authorization, rate limits, or what happens if no recommendations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence efficiently conveys action and sources. Front-loaded with verb and resource, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema provided, but description does not describe what recommendations contain (e.g., field changes, confidence). Missing details on pagination or ordering. Incomplete for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage. Description adds 'from raw_fragments analysis, agent suggestions, or inference' which partially overlaps with source enum. Adds marginal value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'get', resource 'schema update recommendations', and scope 'for an entity type from raw_fragments, agent suggestions, or inference'. Distinguishes from sibling tools like analyze_schema_candidates by focusing on recommendations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like analyze_schema_candidates or other sibling tools. Lacks context about prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already indicates readOnlyHint=true. The description adds that events are chronological and derived from date fields, providing some context beyond the annotation, but does not disclose pagination behavior, ordering defaults, or other traits present in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence immediately states the action and scoping filters. Information is front-loaded and essential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, no output schema, and no parameter description coverage, the description is too brief. It does not explain what constitutes a timeline event, how sources relate to parameters, or the meaning of ordering/pagination. More context is needed for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (no parameter descriptions). The description mentions filter types (type, date range, source) but does not map them to specific parameters (event_type, start_date/end_date, user_id) nor explain limit, offset, or order_by. It fails to compensate adequately for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries timeline events with filters, specifying filter dimensions (type, date range, source). This provides a specific verb and resource, distinguishing it from sibling tools that list other entities like observations or relationships, though explicit differentiation is missing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for querying timeline events with filters but provides no guidance on when to use this tool versus alternatives (e.g., list_observations or list_relationships) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions provenance and historical snapshots but omits key behaviors like the default response format (markdown) for KV-cache stability, the existence of the 'at_ingested' parameter for ingestion-time semantics, and any potential side effects. The schema parameter descriptions provide more behavioral context than the tool description itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the primary purpose, and is entirely free of fluff. It conveys the core function and a key capability without unnecessary detail, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description is too sparse to provide adequate context. It does not explain the response payload, the distinction between 'at' and 'at_ingested', or the optional parameters, leaving a knowledgeable agent to rely solely on the schema. This is incomplete for a tool with four parameters and a rich conceptual model.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, with detailed descriptions for 'at', 'format', and 'at_ingested'. The tool description adds little beyond mentioning the 'at' parameter, and does not clarify 'entity_id' or 'at_ingested'. Since the schema already provides strong parameter semantics, the description's minimal addition keeps this at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves an entity snapshot with provenance information, and explicitly mentions historical snapshot support via the 'at' parameter. This distinguishes it from sibling tools like get_relationship_snapshot or retrieve_entities, though it doesn't explicitly differentiate from all related entity retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for current or historical snapshots but provides no explicit guidance on when to use this tool versus alternatives such as retrieve_entity_by_identifier or retrieve_entities. It does not mention exclusions or when not to use it, leaving usage context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully convey behavior. It states it retrieves entities, implying read-only, but does not mention performance implications of large max_hops, error handling, or response structure. The lack of behavioral details leaves agents uncertain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and key capability. Every word is informative and necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 5 parameters and no output schema, the description is too brief. It omits what the response contains (e.g., entity snapshots, relationship info) and doesn't clarify the role of 'include_entities'. For such complexity, more detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters well. The description adds only high-level context ('n-hop traversal') but no extra parameter-level meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves entities connected via relationships, and mentions n-hop traversal. However, it does not differentiate from similar sibling tools like 'retrieve_graph_neighborhood', which likely serves a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: use when you need connected entities with support for multiple hops. No explicit guidance on when not to use it (e.g., when only direct relationships are needed, or when to prefer 'list_relationships' or 'retrieve_entity_snapshot').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully convey behavior. It only states the output (recommendations with confidence scores) but does not disclose whether the tool is read-only, requires special permissions, or has side effects. This is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action, and contains no extraneous words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, the description should ideally clarify the structure of recommendations. It states 'recommendations with confidence scores' but no further detail on format or nesting. Adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add additional meaning beyond what the schema already provides for each parameter, though it does mention 'confidence scores' which relates to min_confidence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Analyze' and the resource 'raw_fragments' to identify schema field candidates. It distinguishes from siblings like 'get_schema_recommendations' and 'register_schema' by focusing on analysis rather than retrieval or registration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'get_schema_recommendations'). The description does not specify prerequisites or conditions for use, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It mentions rewriting observations and marking source, but does not clarify if source is deleted, whether observations are moved or copied, or any destructive side effects. Missing critical details for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no fluff, front-loaded with the primary action and key effect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should explain return value. Does not mention result of merge (e.g., success/failure, status of source entity). With 4 parameters and no schema descriptions, the description is too sparse for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% parameter descriptions. The description does not explain any parameter (from_entity_id, to_entity_id, merge_reason, user_id) beyond their names. Names are somewhat self-explanatory but incomplete for an agent to invoke correctly without format constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (merge), resource (entities), and the effect: rewrites observations and marks source as merged. It distinguishes from sibling tools like split_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for deduplication, but no explicit guidance on when to use vs alternatives (e.g., delete_entity, split_entity). No prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description claims 'complete' but the schema includes limit/offset for pagination, contradicting completeness. It also omits important traits like that include_observations is entity-only and that results may be truncated. Not transparent about pagination or performance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence, efficient and front-loaded. However, it could be structured better (e.g., bullet points for components) to improve readability, but it's not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters and no output schema, yet the description is very brief. It does not explain the output structure, pagination details (limit/offset), or the distinction between entity and source nodes. For a complex graph retrieval, more detail is needed to be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 no additional meaning beyond the schema; it only lists components covered by parameters like include_relationships, include_sources, etc. No extra context on parameter values or behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('retrieve complete graph neighborhood') and the resource ('around a node'), listing the included components (entities, relationships, sources, events). This distinguishes it from siblings like retrieve_entities or list_relationships that retrieve only specific types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a complete neighborhood is needed but does not provide explicit guidance on when to use this tool versus alternatives like list_relationships or retrieve_related_entities. No when-not-to-use or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'high-priority' and 'always win' but does not disclose side effects, required permissions, reversibility, or behavior on duplicate idempotency keys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundant words, every part adds value. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description lacks return value details, error scenarios, or confirmation of success. For a mutation tool with 6 parameters (including required idempotency_key), more context is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds minimal context beyond the schema (e.g., highlights idempotency_key as replay-safe). It does not explain all parameters in more depth, but schema itself is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a high-priority correction observation to override AI-extracted fields. This verb-resource pairing is specific and distinguishes it from sibling tools like 'create_interpretation' or 'store' that may have overlapping but distinct purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for overriding AI-extracted fields and notes that corrections win in snapshot computation, but does not explicitly state when to use this tool vs alternatives (e.g., 'create_interpretation' for non-correction observations) or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It adds context about the remote health check including '/health probe' and 'semver compat vs this server', but does not disclose potential error conditions, authentication needs, or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action and resource. It wastes no words, though slightly more structure could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description lacks completeness. It does not explain the output structure, error handling, or prerequisites, leaving an agent with insufficient information for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It mentions 'peer_id' as the identifier but adds no details on format, constraints, or how the parameter is used beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch peer_config by peer_id plus remote_health', specifying the action and resources. It distinguishes itself from sibling tools like 'list_peers' by focusing on a single peer's detailed status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need peer config and health for a specific peer, but provides no explicit guidance on when to choose this tool over alternatives like 'list_peers' or 'sync_peer'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only mentions 'create' and assumes existing entities. Lacks details on error handling, authentication, side effects, or idempotency. Minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise three-sentence description: purpose, type list, and special usage. Front-loaded with primary action. No fluff, but could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key points but lacks error behavior, return value (no output schema), and prerequisites for entity existence. Adequate for basic understanding but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions; description adds value by explaining EMBEDS usage, metadata fields, and workflow for file attachments, compensating beyond raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a typed relationship between two entities and lists relationship types. It does not differentiate from sibling 'create_relationships' but the singular form implies single relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides specific guidance for EMBEDS type with step-by-step workflow for images/files. Does not explicitly address when to use alternatives or when not to use, but context is clear for given case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only notes webhook secrets omitted. Lacks disclosure of side effects, auth requirements, rate limits, or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear verb and caveat. Front-loaded and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or annotations. Description is minimal but adequate for a simple list; lacks explanation of return format, pagination, or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters (baseline 4). Description adds meaning by specifying scope and omission, which is helpful beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'List', resource 'subscriptions', scope 'current user's active', and caveat about webhook secrets. Distinguishes from siblings like 'subscribe' and 'unsubscribe'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., subscribe, unsubscribe) or context for the list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It reveals that other entity types may result in a no-op, which is helpful. However, it does not disclose side effects (e.g., overwriting, destructive actions) or permissions needed, leaving moderate gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that packs key information: purpose, scope (issue to GitHub), and caveat (no-op for others). It is front-loaded and concise, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input (one optional param) and no output schema, the description is fairly complete. It explains the primary use case and limitations, but leaves open questions about what 'sync' entails (direction, idempotence, success/failure behavior) and what 'external mirrors' refers to.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers the default behavior ('Defaults to issue when omitted'), and the tool description adds meaning by explaining that 'issue' triggers GitHub sync while other types are no-ops. This goes beyond the schema, providing valuable context for parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool syncs external mirrors for submissions and gives a specific example (issue to GitHub sync). It uses a specific verb and resource, but does not explicitly distinguish itself from the sibling tool 'sync_issues', leaving slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for syncing issues to GitHub and notes that other types may no-op until providers are added, providing some context. However, it lacks explicit when-to-use or when-not-to-use guidance and does not mention alternatives like 'sync_issues'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that secrets are redacted, which is a behavioral trait. However, it does not mention idempotency, authentication requirements, or output format. For a simple list operation, this is acceptable but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that effectively communicates the purpose and key behavioral note. No extraneous words; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), the description covers the essential aspects: purpose and secrets redaction. It could be slightly more explicit about returning all rows, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so schema description coverage is 100%. The description does not add parameter information, but none is needed. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists peer_config rows for the current user, with a note about secrets redaction. It uses a specific verb and resource, and the scope is explicit. It distinguishes from sibling tools like add_peer or remove_peer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives like get_peer_status or sync_peer. The name and description imply it's for listing, but no when-to-use or when-not-to-use information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns the user_id and notes its automatic use in authenticated actions. With no annotations, it adequately communicates the core behavior, though it could mention if the result is cached or requires prior authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The description is front-loaded with the action and resource, making it efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return value ('user_id') and its significance ('automatically used for all authenticated actions'). This is sufficient for a simple tool, though it could specify the data type or format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the schema coverage is 100%. The description adds no parameter information, which is acceptable since none are needed. Baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the authenticated user ID with a specific verb ('Get') and resource ('authenticated user ID'). It is unambiguous, but does not differentiate from sibling tool 'get_session_identity' which may serve a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_session_identity'. The description lacks context for appropriate usage scenarios or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It states the output is a snapshot and that the webhook secret is omitted, which is useful. However, it does not disclose permissions, error conditions, or whether the operation is a read (implied by name but not explicit). Lacks details on side effects 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the main action, and includes a clarifying parenthetical. Every word earns its place; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required param, no output schema, no annotations), the description is nearly complete. It tells what it returns and what is omitted. However, it could mention potential null return or error cases, but for a basic retrieval, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, requiring the description to compensate. The description only says 'by subscription_id', adding little beyond the schema's property name. It does not explain the format, constraints, or how to obtain the ID. Baseline would be 3 if coverage were high, but here it's low and the description fails to fill the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Return one subscription snapshot by subscription_id', which is a specific verb and resource. It distinguishes from siblings like list_subscriptions (which returns multiple) and subscribe/unsubscribe (which are mutations). The parenthetical note about omitting webhook secret adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need a single subscription snapshot, but does not explicitly state when to use this vs. alternatives (e.g., list_subscriptions for multiple, subscribe for creation). 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose all behavioral traits. It mentions creating a row and optional thread/token, but does not discuss side effects, idempotency, authorization needs, or what happens to existing submissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose, then details optional outputs, then provides an alternative—all in 20 words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should hint at return values, but it does not. It covers the core function but omits behavioral context and output characteristics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 context that fields is the payload and initial_message relates to conversation, but does not significantly enhance understanding beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a generic submission for entity types with an active submission_config, creates the primary row plus optional conversation thread and guest_access_token, and explicitly distinguishes from submit_issue for GitHub-backed issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It names the alternative submit_issue for GitHub-backed issues, providing clear differentiation. However, it does not elaborate on prerequisites or when not to use this tool beyond that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It indicates a write operation ('append') and adds context ('follow-up', 'submitted root entity'), but does not mention permissions, idempotency, or what happens if the entity is not submitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the purpose and key details. No extraneous words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 the action and parameter roles. It assumes prior context (entity already submitted, thread exists), which is reasonable given the tool name. Minor gap: no mention of message size limits or handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with adequate parameter descriptions. The tool description adds minor value by framing the message as a 'follow-up conversation' and connecting entity_id to a 'root entity', but does not significantly enhance meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Append a follow-up conversation_message'), the resource ('thread for a submitted root entity'), and references the key parameter 'entity_id'. It distinguishes from the sibling 'add_issue_message' by specifying it is for entities, not issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a user wants to add a follow-up message to an entity's thread, but it does not explicitly state when to use this tool versus alternatives like 'add_issue_message'. No when-not or prerequisite guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation 'readOnlyHint: true' already indicates a safe read operation. The description adds context about the tables scanned, ordering by 'activity_at', and authentication requirement, which enriches the behavioral understanding beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the tool's purpose and key behavioral details (tables, ordering, authentication). No redundant information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not specify the structure of returned items (e.g., whether they contain full records or just IDs). Given the tool aggregates across multiple tables, more detail about the output format would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters (limit, offset) have clear descriptions in the input schema. The description does not add any parameter-specific meaning; it only mentions ordering. With high schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'recently changed records across core Neotoma tables', and specifies the scope 'for the authenticated user'. It distinguishes itself from sibling list tools like list_interpretations or list_observations by aggregating across multiple tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving a recent activity feed, but it does not explicitly state when to use it versus the many sibling list tools (e.g., list_entity_submissions, list_relationships). No 'when not to use' or alternatives are provided, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the operation's effect (overrides deletion, makes visible, immutable) but lacks details on permissions, idempotency, error conditions, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The operation is simple, but with no output schema and no annotations, the agent is left uncertain about the return value, error handling, or prerequisites (e.g., entity must be deleted). Additional context on behavior would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a basic description. The tool description adds audit context ('reason' for audit) but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Restore a deleted entity'), the mechanism ('creates a restoration observation'), and the result ('becomes visible'). It distinguishes from siblings like 'delete_entity' and 'restore_relationship' by focusing on entity restoration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after deletion and mentions 'immutable restoration for audit,' which guides when to use it. However, it does not explicitly specify when not to use it or contrast with alternatives like 'restore_relationship.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses delivery methods, filter requirements, and sync_peer_id functionality. Missing details on authentication, rate limits, error conditions, or what happens on failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose. Every sentence adds value without redundancy. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should hint at return value (e.g., subscription ID). It does not. Lacks authentication info but covers filters and delivery methods adequately. Moderate complexity; missing return info reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 8 parameters with only 13% description coverage (only sync_peer_id described). The tool description adds meaning: explains filter requirement and loop prevention for sync_peer_id, but does not elaborate on webhook_url, webhook_secret, max_failures, or delivery_method semantics beyond listing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create' and the resource 'substrate event subscription' with specific delivery methods (webhook with HMAC, SSE). It distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by detailing the creation process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisites: at least one filter among entity_types, entity_ids, or event_types. Also explains the use of sync_peer_id for loop prevention. However, it does not mention when not to use this tool or compare with alternatives like 'get_subscription_status'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description reinforces this with 'snapshot' and 'read-back'. It adds specific context about token-scoped access without contradicting annotations. No additional behavioral traits disclosed, but sufficient given annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear structure, front-loading the core action and then specifying the optional parameter. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with annotations, the description covers the purpose and key parameters. However, without an output schema, it lacks details on the return structure or error behavior, leaving minor gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: guest_access_token has a description in the schema, entity_id has none. The description mentions both parameters but adds minimal semantics beyond what the schema provides (e.g., no format or constraint details). Adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool returns a JSON entity snapshot for a submitted entity_id, with optional guest_access_token for token-scoped read-back. It distinguishes itself from sibling tools like get_issue_status or get_relationship_snapshot by focusing on entity submissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (for retrieving a submission snapshot) but does not provide explicit when-to-use vs alternatives, nor exclusion criteria. The guest_access_token is mentioned but not explained when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which the description supports by stating 'Return'. Additionally describes sync skipping behavior and token scope for remote read-through, adding 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second covers parameter usage. No superfluous words; information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 states that status and thread messages are returned. Could be more detailed about structure, but covers the essential return content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds minor value by clarifying usage of guest_access_token and noting issue_number is an integer, but does not significantly extend schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Return issue status and thread messages' with specific resource (issue) and verb (return). Distinguishes from siblings which are for other operations like creation, update, or deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on how to identify the issue (entity_id or issue_number) and when to use guest_access_token. Lacks explicit when-not-to-use or comparisons with alternatives like get_entity_submission_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses the check logic and auto_fix action, but does not explain what recompute entails (e.g., permissions, side effects) or return details like health status format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The primary purpose and key parameter are front-loaded. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and one optional parameter, the description sufficiently explains purpose and auto_fix. However, it could explicitly state the return type (e.g., a JSON object with 'stale_count'), but overall it's adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds meaning by explaining auto_fix default and effect. The description goes beyond schema by clarifying the conditional recompute behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks for stale entity snapshots, defines the condition (observation_count=0 with existing observations), and specifies outputs (health status and count). It uses specific verb and resource, distinguishing it from unrelated tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for monitoring snapshot health, but does not explicitly state when to use it versus other tools or provide exclusions. No guidance on alternatives like other health checks is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses creation of a restoration observation (priority 1001) and immutability for audit. However, it omits side effects, permissions, or failure conditions (e.g., if relationship not found).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding unique information: purpose, mechanism, and audit property. No redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description effectively explains what the tool does and its audit trail. Lacks error handling or result details, but sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds minimal value beyond schema, only noting reason as optional for audit and user_id inference. Does not clarify parameter constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it restores a deleted relationship, differentiating from create_relationship and delete_relationship. It specifies the mechanism (restoration observation) and effect (visible again).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates use after deletion, but does not explicitly exclude scenarios like restoring an already active relationship or provide alternatives. Clear context but lacks explicit 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: fallback to semantic search, short-circuit for entity_id, optional observations, and hints for missing ids. It does not cover authentication or rate limits but covers the main behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two sentences that front-load the purpose and then add critical behavioral details. Every sentence contributes value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (6 params, no output schema), the description covers the search algorithm, optional observations, and sibling tool hint. It lacks return value specifics but is largely complete for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 minimal parameter-specific context beyond the schema (e.g., normalization of identifier). It does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (retrieve), resource (entity), and the method (by identifier). It distinguishes from sibling tools like retrieve_entity_snapshot by noting the short-circuit behavior for literal entity_id and the hint to that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied but not explicitly stated. The description explains the fallback and short-circuit behavior but does not provide direct guidance on when to use this tool versus alternatives like retrieve_entities or retrieve_entity_snapshot.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behaviors: soft deletion via an observation, immutability, reversibility, and effect on snapshots/queries. It does not cover potential side effects like cascading or notifications, but adequately conveys the audit-friendly nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded with the core action. Every sentence adds value: the first defines the operation, the second explains the mechanism and use case. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what happens to the entity and its observability, but does not mention the return value or confirmation (e.g., whether an observation ID is returned). Given no output schema, the agent may lack clarity on the expected response, making it minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters, so the description adds no extra meaning beyond what the schema provides. The baseline score of 3 is appropriate as the schema already documents the parameters clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes an entity and explains the mechanism ('creates a deletion observation'), distinguishing it from hard delete or restoration tools like restore_entity. The verb and resource are specific, and the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool ('user-initiated or GDPR-style removal'), but does not explicitly mention alternatives or when not to use it. It implies the tool is for soft deletion with audit trails, but could contrast with sister tools like merge_entities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that it uses the same aggregation as GET /stats and sorts results. It does not mention any destructive behavior, which is expected as it is a read operation. However, it could add more detail about output format or pagination, but for a simple count tool, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently written in two informative sentences plus a third sentence differentiating from a sibling. There is no filler, and it is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema, common read operation), the description is complete enough. It explains the return type (canonical entity counts), aggregation source, sorting, and usage context. No additional information is necessary for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (user_id) already described as optional and inferred from authentication. The description adds no further parameter details beyond what the schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns canonical entity counts by entity_type, using the same dashboard stats aggregation behind GET /stats, and sorts results by count descending then entity_type ascending. It also distinguishes itself from list_entity_types by specifying that this returns row counts while that returns field width.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: 'Use this when the user asks for counts by type, histograms, or sorted totals.' It also mentions when not to use it by contrasting with list_entity_types. However, it does not explicitly state when not to use or provide alternative tools beyond the one sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains what the tool computes and how entities are resolved, but does not disclose whether it is read-only/destructive, nor any 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but concise; every sentence adds value. The ticket number 'FU-2026-05-002' is slightly extraneous but does not detract significantly. Front-loaded with main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains what the returned status_line and widget_uri are for. Missing explicit return structure and error handling, but adequate for a straightforward compute tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: specifies turn_key format, explains conversation_id disambiguation, and notes server entity resolution. Only user_id lacks description in both schema and text, but it's optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool computes the per-turn Neotoma status line and optional widget URI, with clear verb-resource pairing. The task is unique among siblings, no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly says when to call 'at the end of every turn after the closing assistant store completes.' Does not explicitly state when not to call, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description shoulders the disclosure burden. It discloses content-addressed storage ('SHA-256 dedup per user'), response content ('source_id / content_hash'), and the no-auto-interpretation behavior ('server does not invent structured fields... without an explicit interpretation block'). It doesn't mention merge/overwrite behavior, but the disclosed details go well beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a well-structured paragraph with no fluff. Each sentence contributes new information: purpose, routing, combined-call capability, file behavior, interpretation limitation, and field-handling rule. It front-loads the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 17-parameter tool with nested objects and no output schema, the description covers the core ingestion model (entities vs files, combined requests, dedup, interpretation, field routing). It does not cover relationships, commit/strict modes, or provenance fields, but those are documented in the schema with high coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 88%, so the schema already documents most parameters. The description adds value by mapping source types to parameter groups (file_content+mime_type/file_path vs entities), and by explaining field routing ('Schema fields go to observations; non-schema fields go to raw_fragments'). This supplements the schema's per-field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Unified storing for structured, file-backed, or combined payloads in one request,' clearly identifying the tool as a combined ingestion endpoint for entities and files. It doesn't explicitly name sibling alternatives, but the source-routing instructions ('file- or resource-sourced → use file_content+mime_type or file_path; conversation- or tool-sourced → use entities') clarify what it stores and how to select the right input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It offers explicit decision rules: 'Choose path by source' with mapping to file vs entities parameters, and advises 'Agents should parse and extract entities first... then send those entities alongside the raw file.' It lacks a when-not-to-use statement or sibling tool references, but the routing guidance is concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides substantial behavioral details: push leg sanitizes PII, creates new issues on GitHub, updates locally; pull leg retrieves issues and messages. It does not cover error handling, concurrency, or atomicity but offers a clear picture of the two legs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each earning its place: first sentence defines core function, then push leg, pull leg, and filtering support. No fluff, front-loaded with key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 100% schema coverage, the description lacks details on return values, conflict resolution, and error handling. For a sync tool with no output schema, more completeness would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing a baseline of 3. The description adds meaning by clarifying that push only acts on local public issues without github_number, and that push is enabled by default. This contextualizes parameters beyond their schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a bidirectional sync between local Neotoma and GitHub repo, specifying push and pull legs with distinct behaviors. This verb+resource definition distinguishes it from sibling issue tools like submit_issue or get_issue_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for synchronizing local and GitHub issues, detailing the default push leg and filtering options. However, it does not explicitly mention when to use alternatives (e.g., submit_issue for single issue creation) or when to avoid this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden. It discloses output structure (best_match, identity_score, etc.) but does not mention side effects, idempotency, or authentication requirements. For a resolution tool, this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and output structure. No superfluous words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested signals, multiple parameters, no output schema), the description adequately covers return values and usage scenario. It does not explain the resolution algorithm fully, but that level of detail is unnecessary for agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by explaining canonical weights for well-known keys and weight 0.4 for open-ended keys, which the schema lacks. This aids the agent in understanding signal importance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: resolving an entity from a multi-signal bundle (name, email, company, domain, phone, open-ended strings). It specifies output fields (best_match, identity_score, resolution_band, etc.), distinguishing it from sibling tools like retrieve_entities that use exact IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use when you have partial or combined identity information and want a single-call resolution with confidence scoring.' It does not explicitly state when not to use or list alternatives, but the context of sibling tools implies alternatives for exact ID lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses read-only behavior, return structure (including order), and purpose. No contradictions or hidden behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet thorough: main purpose first, then return details, then usage. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description compensates with detailed return structure. Missing explanation of user_id param limits completeness slightly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (user_id lacks description). The description adds context for entity_type but omits user_id entirely. This leaves the agent guessing about user_id's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports undeclared fragments and contrasts with siblings like update_schema_incremental. The verb 'Report' and resource 'undeclared raw_fragments' are specific, and the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use it for triage before schema work, and mentions optional entity_type scoping. It doesn't explicitly state when not to use, but the read-only nature is clear from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It states the tool does not write any rows, which is good. However, it lacks details on potential performance impact, authentication requirements, or any rate limits that might affect usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the purpose, and includes critical usage guidance. Every word contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 lists the key fields returned (trust tier, AAuth/clientInfo, anonymous-write policy, write eligibility) and clarifies safety. This is complete for a simple, zero-parameter introspection tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema coverage is trivially 100%. The description does not need to add parameter info. Per the guideline, 0 parameters yields a baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves the current session's attribution details including trust tier, AAuth/clientInfo fields, and write eligibility. It distinguishes itself from sibling tools like get_authenticated_user by focusing on session identity rather than just user info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states it is safe to call as a preflight health check and does not write any rows, which guides when to use it. However, it does not explicitly mention scenarios to avoid or alternative tools for related queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses side effects ('If remote append fails after local/GitHub side effects') and error handling, though it does not explicitly state the write nature (implied by 'append').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. Every sentence conveys essential guidance including alternatives and error handling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description covers error handling and side effects. Given 8 parameters (1 required), it provides sufficient context for an agent to invoke correctly, though success behavior is not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by clarifying the optionality between entity_id and issue_number and explaining the purpose of guest_access_token beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Append a message to an issue thread' with a specific verb and resource. It distinguishes from sibling 'add_entity_message' by targeting issues explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use entity_id vs issue_number, when to pass guest_access_token, and how to handle remote_submission_error. Lacks explicit when-not-to-use or direct alternative tool names, but context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully discloses behavior: read-only, no persistence side effects, returns schema details, and errors with InvalidParams when no active schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat verbose but well-structured, front-loading key return info, then usage guidance. Every sentence adds value, though could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description compensates by detailing return fields and error handling. It covers workflows and preconditions. Lacks parameter descriptions, but overall complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, requiring description to explain parameters. Description uses 'entity_type' and 'user_id' but only acknowledges entity_type's purpose ('one entity_type'). user_id is not described beyond its name, leaving ambiguity about its role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the full active schema for an entity type, listing specific components like field_names, field_summary, required_fields, etc. It distinguishes itself from siblings by specifying when to call it (before store or in repair workflow).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use: before store when field shape unknown, and in repair workflow after unknown_fields warnings. Also advises when not to use (only add new field if no declared field fits) and references alternatives (update_schema_incremental, register_schema).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses key behaviors: two modes of operation, hybrid search mechanism, meaning of field_count. Lacks details on pagination or rate limits but sufficient for core functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single well-structured paragraph, front-loaded with purpose, then behavior details. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, two modes, hybrid search), the description covers the key behaviors and return structure hints. Could mention user_id role and edge cases, but sufficient for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description explains keyword and summary parameters thoroughly. user_id is not explained, leaving a gap, but the other two parameters are well-covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available entity types, with distinct behaviors for with and without keyword. It distinguishes itself from sibling tools like get_entity_type_counts and retrieve_entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use before storing structured data to determine the correct entity_type', giving clear when-to-use guidance. Does not mention when not to use or alternatives, but sibling tools are distinct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that soft-deleted relationships are excluded by default, explains the include_deleted parameter, and mentions pagination via limit/offset. It does not cover auth needs or rate limits, but the behavioral details are sufficient for most use cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured. It starts with the main purpose, then details filtering options, a specific use case, default behavior, and pagination. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 optional parameters and no output schema, the description covers the main use cases, filtering, and pagination. It mentions that each returned relationship carries its relationship_type, but does not describe the full output structure (e.g., source/target entity IDs). A brief note on the response format would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, setting a baseline of 3. The description adds value by explaining the relationship between entity_id and direction, the use case for combining source_entity_id and target_entity_id, and the meaning of include_deleted. This goes beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists relationships for an entity or discovers relationship types between two specific entities. It distinguishes between filtering modes and provides a specific use case (discovery before deletion), differentiating it from sibling tools like create_relationship or delete_relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use entity_id with direction vs. source_entity_id/target_entity_id. It also includes a concrete example for discovering relationship type before deletion. However, it lacks explicit 'when not to use' or alternatives, which would elevate it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description handles transparency. Mentions no storage and output of text and images, but lacks detail on error handling, output format, or behavior with large files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words. Highly concise and easy to process.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should clarify return format. Mentions 'text and first-page PDF images' but not structure or data type. Good for intended use but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The tool description adds context about preferred local file path but doesn't significantly enhance per-parameter semantics beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it parses files into text and first-page PDF images, and explicitly says it does not store anything, distinguishing it from the 'store' sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'Use before store when you need to extract entities from a file.' Provides clear guidance on context and intended workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral burden. It explicitly discloses read-only behavior ('never creates a company entity'), the no-match return shape ('company: null and an empty contacts list'), the owner_user_id restriction ('must equal the authenticated user's id today'), and the resolution algorithm. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph, but every clause earns its place: purpose, resolution order, read-only guarantee, no-match behavior, and owner scoping. It is front-loaded with the purpose and uses a clear colon to separate the core question from details. No redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers resolution, read-only behavior, no-match scenarios, and owner override thoroughly. Since there is no output schema, it briefly mentions response elements (company:null, empty contacts, total_contacts in schema) but does not fully enumerate the response fields. Still, for a query tool of this complexity, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all three parameters, and the schema already explains limit, company_name matching, and owner_user_id semantics. The description adds context about resolution order and the live edge, but does not significantly enrich parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the exact question it answers ('who do we have connected at company X') and clearly states it returns every contact linked to the resolved company via a live works_at edge. This specifies the verb (query/return), resource (contacts at a company), and scope (canonical company entity), and differentiates it from sibling tools like list_relationships by focusing on company resolution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use when you need contacts linked to a company, with optional owner scoping. It explains the resolution order (exact-normalized then fuzzy) and the read-only nature, but does not explicitly name alternative tools or state when not to use this tool. This meets 'clear context, no exclusions'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It is exceptionally transparent: it explains the authentication model (no Bearer token, AAuth signature, or guest token needed), that the token is an OUTPUT rather than a precondition, that anonymity covers only the submission, and the deprecated visibility alias behavior with exact response text. This gives the agent essential context about side effects and security aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries relevant information: purpose, token return, auth model, follow-up usage, required parameters, and deprecation warning. It is front-loaded with the main action. It could be better structured with bullet points for readability, but it is not verbose or wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters, no output schema, and no annotations, the description compensates well by explaining the return token, auth preconditions, required params, and deprecation behavior. It does not elaborate on all potential side effects (e.g., GitHub mirror behavior, error cases), but covers the most critical contextual information an agent needs to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by reinforcing the conditional requirement for reporter_git_sha/reporter_app_version (already in schema) and, more importantly, by documenting the deprecated 'advisory' enum value for visibility, which is not present in the schema. This extra semantic detail about an accepted value improves parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Submit an issue') and target ('configured operator Neotoma instance'), with a specific verb and resource. It distinguishes this from sibling tools by naming the follow-up token-scoped read-back tools (get_issue_status / add_issue_message), making it clear this is the initial submission action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: it states when this tool is appropriate (submitting without prior identity), what must be provided (at least one of reporter_git_sha or reporter_app_version), and how to proceed after acceptance (use returned token for get_issue_status/add_issue_message). It also notes the deprecated visibility alias, giving clear exclusions. However, it does not explicitly mention alternative tools for cases where a guest token already exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosure. It thoroughly explains the tool's behavior: it fetches npm registry data, includes optional release notes and capability delta, indicates best-effort nature, and clarifies conditions under which fields appear (e.g., capability_delta_note only on degradation). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but each sentence contributes necessary detail. It fronts the core purpose and then systematically lists return fields and conditions. Could be slightly more concise, but the complexity of the tool justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description fully documents all return fields and their conditional presence. It covers every aspect of the tool's behavior, leaving no ambiguity for an AI agent to invoke or interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by explaining the effect of each boolean flag on the return object (e.g., include_release_notes adds release_url and excerpts; include_capability_delta adds new_tools, removed_tools, etc.). This goes beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Check if a newer npm version is available', a specific verb and resource. It then details the return values, clearly distinguishing this tool's purpose from any sibling tools, none of which deal with npm version checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Call at session start to encourage user to upgrade'), providing clear context. It does not mention when not to use it or alternatives, but given the unique purpose among siblings, this is not a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels: it explains action-specific outputs, persisted state toggling, exceptions for default bundles, side effects of disabling (stops auto-creating types while preserving data), and the return type (structured JSON). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: three sentences with the main verb+resource up front, followed by action details and constraints. Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description covers all action types, required parameters, exceptions, side effects, and return format. The tool's complexity is fully addressed in a compact space.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameters already have descriptions, but the tool description adds behavioral meaning beyond the schema (e.g., what happens when disabling a bundle, what list returns). This goes beyond the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Inspect and manage Neotoma bundles' and enumerates specific actions (list, info, install, enable, disable) with distinct outcomes. This differentiates it from sibling tools focused on entities, relationships, and other domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context for each action (e.g., 'action=info (with bundle) returns full manifest detail') and notes constraints like default-install bundles cannot be disabled. It does not explicitly name alternative tools, but the sibling list shows no overlapping bundle tools, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: each call mints a fresh token, tokens are hash-only at rest, html_body is injected verbatim without wrapper elements, and idempotency key behavior for inline creation. These details go beyond the schema and annotations (which are absent), fully informing the agent of side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense paragraph that front-loads the purpose and then efficiently covers details. Every sentence adds value, with no repetition or fluff. It is well-structured for an AI agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the major aspects: usage modes, parameter behavior, token generation, and return value. It lacks error handling specifics and does not mention authentication requirements beyond 'user_id inferred from authentication.' Given the complexity (7 parameters, multiple modes), it is fairly complete but could include a brief note on failure cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema already has 100% description coverage, the description adds significant context: it explains the two usage modes (entity_id vs. inline fields), the verbatim injection of html_body, the purpose of idempotency_key, and the optional nature of user_id. This adds meaning beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: turning a rendered_page into a ready-to-share guest URL. It outlines two distinct usage modes (pass an existing entity_id or create one inline) and specifies the return value (absolute URL with token and TTL). No sibling tool offers similar functionality, so it effectively distinguishes itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (to publish a rendered page) and the two modes. It does not explicitly exclude scenarios or mention alternatives, but given the sibling list lacks a direct alternative, a score of 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: observations are never modified, only FK rebound; idempotency and error conditions (ERR_IDEMPOTENCY_MISMATCH); relationships are not affected. This is comprehensive for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3 sentences) and front-loaded with the core purpose. It efficiently covers key behavioral aspects without unnecessary detail. Slightly dense but well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, nested objects, no output schema), the description provides a solid overview of purpose, behavior, and parameter usage. However, it could briefly mention the expected response format or success indicators.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 50% of parameters with descriptions, but the description adds significant value by explaining the predicate forms and their use cases (e.g., 'move every observation from this session forward'). It also clarifies idempotency_key semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is the inverse of merge_entities, specifically repoints observations to repair over-merges. It provides a concrete use case (pre-v1.2 heuristic name_key:title collapse) and distinguishes it from its sibling, merge_entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (repair over-merges) and when not to (typed relationships remain bound, use create_relationship instead). Also notes idempotency key reuse behavior, giving clear guidance on proper invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly: it discloses that activation is immediate, existing observation data is preserved and snapshot-excluded, migration is optional, existing reducer_config is preserved, re-keying does not retroactively merge duplicates, and passing [] clears only when identity_opt_out is declared. These are exactly the non-obvious behavioral traits an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but justified by the tool's complexity (9 parameters, nuanced identity rules). It front-loads the core purpose in the first paragraph and then detains on canonical_name_fields in a well-separated second paragraph. Every sentence carries information; the length is a function of necessary detail rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 9 parameters, the description is remarkably complete. It covers activation, migration, version-bump behavior, identity-rule semantics, edge cases (clearing rule, identity_opt_out), and the non-retroactive nature. It does not need to describe return values because no output schema is provided, but it does mention the response echoes canonical_name_fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema already covers all parameters (100% coverage), the description adds significant operational meaning beyond the schema. For canonical_name_fields it explains ordered precedence with a concrete example ([{composite:['linkedin_url']},'email','name']), the collision scenario, and the 'safe way' framing. It also ties fields_to_add/remove to version bump semantics, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Incrementally update a schema' and enumerates three distinct operations (adding fields, removing fields, changing identity rule), each with explicit version-bump consequences. This clearly distinguishes it from siblings like register_schema, and the text even contrasts it: 'safe way to re-key without a full register_schema re-supply.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a concrete use case: 'Reach for it when same-name-different-entity collisions appear' and cautions that re-keying applies to new writes only. It names an alternative (register_schema) and instructs to call describe_entity_type first, but does not explicitly list exclusions (e.g., when a full re-registration is required).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully covers behavioral traits: read-only, fuzzy post-hoc detector, never auto-merges, threshold override. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding essential information. No wasted words. Purpose, usage, and behavior are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description covers key aspects: input, behavior, and next steps. Minor missing detail on return format (e.g., pairs with similarity scores), but sufficient for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage for 4 parameters. Description adds meaning by explaining that per-schema thresholds come from schema fields and callers may override threshold per call, going beyond raw schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists candidate duplicate entity pairs for a given entity_type. Distinguishes itself from sibling merge_entities by explaining it is the detection step before merging.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says it is read-only and never auto-merges, advises confirming with user before calling merge_entities. Explains threshold behavior and override capability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes side effects (deletion observation, exclusion from snapshots/queries), audit immutability, and error response (404 with discovery hint). No annotation contradicts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Few sentences, each essential: action, prerequisite, behavioral effect, error handling. Front-loaded with core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given full schema and no output schema, description explains return behavior and side effects completely. No gaps for an agent to make errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters. Description adds value by specifying that relationship_type must be exact and advising to discover it via list_relationships if unknown.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a relationship' – a specific verb and resource. Distinguishes from sibling tools like 'create_relationship' and 'restore_relationship' by mentioning immutability and audit trail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use list_relationships first when relationship_type is unknown. Provides clear preconditions and what to do in case of no match (404 hint).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses strict-mode combination rules, alias handling, cursor and offset limitations, snapshot_filters behavior including `contains` vs `contains_word` semantics, case-insensitivity, and performance implications of include_snapshots. This significantly exceeds standard behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely informative with no filler. It is front-loaded with the primary use-case and then systematically covers constraints, filtering, and pagination. Every sentence provides actionable guidance for a high-complexity tool (21 params).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 21 parameters, nested snapshot_filters object, and no output schema/annotations, the description covers use cases, constraints, filter semantics, pagination strategy, and performance advice. It mentions response elements (next_cursor, snapshot payloads) and error behavior. It is unusually complete for such a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 21 parameters (100%), but the description adds substantial meaning: explains why limit is capped at 500 with snapshots, clarifies cursor vs offset trade-offs, snapshots filter operators with examples, lexicographic sort behavior, and the compatibility aliases. This is well beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Use this when you need filtered entity lists' and 'lexical/semantic retrieval via search', clearly specifying a list/query operation on entities. It distinguishes from siblings like retrieve_entity_snapshot (single entity) by focusing on filtered lists and search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with 'Use this when you need filtered entity lists' and provides explicit constraints: search cannot combine with non-default sorting or published filters; include_snapshots=false for lightweight responses; cursor vs offset for deep pagination. Gives guidance on when to use snapshot_filters and compatibility aliases, plus conditions when cursor is unsupported.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![neotoma MCP server](https://glama.ai/mcp/servers/markmhendrickson/neotoma/badges/card.svg)](https://glama.ai/mcp/servers/markmhendrickson/neotoma)

Score Badge

Copy to your README.md:

[![neotoma MCP server](https://glama.ai/mcp/servers/markmhendrickson/neotoma/badges/score.svg)](https://glama.ai/mcp/servers/markmhendrickson/neotoma)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/markmhendrickson/neotoma'

If you have feedback or need assistance with the MCP directory API, please join our Discord server