Persistent project context for Claude. IANA-registered .faf format.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 3.9/5 across 19 of 19 tools scored. Lowest: 3.3/5.
Several scoring tools overlap heavily: faf_score, faf_validate, faf_analyze, faf_gate, and refresh_faf all evaluate .faf content and return related quality verdicts, making selection difficult. The retrieval surface also overlaps across faf_section, faf_collections_search, faf_memory, search_context, and search_by_tag, dividig search across several subtly different stores and modes.
Most tools follow snake_case and use either the faf_ prefix or clear verb-noun pairs like list_souls, get_soul, and search_context. Minor deviations like delta_check and tag_intel do not seriously obscure the overall naming pattern.
19 tools is on the heavy end, and several scoring/search tools could be consolidated into fewer composite actions without losssing capability. It is not extreme, but the set is larger than the core FAF + soul workflow needs.
The FAF workflow is mostly covered by validation, scoring, tiers, gateing, refresh, orchestration, generation, and retrieval. However, there are no create/update/delete operations for souls or persisted memories, and generation only accepts GitHub repos rather than arbitrary content, leaving meaningful lifecycle gaps.
delta_checkDelta Doctrine CheckADetermine if a topic needs FULL, DELTA, or X-DELTA soul.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Topic to check |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate that the tool is read-only, idempotent, and non-destructive. The description adds the classification outcomes (FULL, DELTA, X-DELTA), but does not disclose edge cases, ambiguity handling, or default behavior. This is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, immediately readable sentence with no filler or repetition. It states the command, the subject, and the possible outputs compactly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter classifier with strong annotations, the description is mostly complete: it names possible outcomes and the input. However, no output schema exists and the description does not explicitly state whether the tool returns one of the three labels, whether it returns a broader rationale would be acceptable, or how malformed or unknown topic topics are handled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter, 'topic', and the schema description already provides 100% coverage. The description repeats that the topic is the object being evaluated but adds no further format, constraints, or examples beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'determine', and names the resource and result categories (FULL, DELTA, or X-DELTA soul), so an agent can understand the tool's core function. It does not explicitly distinguish itself from siblings, but the classification intent is clear enough for a tool with this scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: call this when you need to decide which soul level a topic requires. The description gives no explicit when-not-to-use guidance or alternatives, but for a small deterministic classifier this may be sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faf_analyzeFull analysis (score + tier + validate)AOne-call composite — returns score, tier-ready, valid, and engine identifier. Two WASM calls, sub-millisecond total.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Raw .faf YAML content to analyze. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context beyond annotations by disclosing that two internal WASM calls are made, total latency is sub-millisecond, and the response includes an engine identifier. No contradiction with annotations found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, information-dense sentences. It front-loads the tool's composite nature and then gives the two details that matter most: output contents and performance characteristics. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter schema, full schema documentation coverage, and strong safety annotations, the description covers the essential inputs, outputs, and side effects. The main gap is the lack of explicit comparison to sibling tools for when a caller should choose only faf_score, faf_get_tier, or faf_validate instead.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'content' is fully described in the input schema as 'Raw .faf YAML content to analyze,' giving 100% schema coverage. The description does not add parameter-level detail, but it does not need to because the schema already carries the meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear composite purpose: 'One-call composite — returns score, tier-ready, valid, and engine identifier.' It distinguishes itself from single-purpose siblings like faf_score, faf_get_tier, and faf_validate by making the composite nature explicit, though it does not name those siblings directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'one-call composite' phrasing implies this tool should be used when a caller wants score, tier, and validation together instead of making separate calls. However, it never explicitly states when not to use it or which alternatives to prefer for partial analysis, leaving usage primarily implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faf_collections_searchSearch a Grok Collection (edge, KV-cached)APhase III (FRC §7b) — semantic search over a Grok Collection at the edge, KV-cached (1h TTL). Returns matched chunks (content, score, file). Requires the XAI_API_KEY secret; composes with faf_section (structural) for hybrid retrieval. Handled env-aware in the MCP handler (needs the key + KV).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max chunks to return (default 5). | |
| query | Yes | The search query. | |
| collection_id | Yes | The Grok Collection id to search. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read-only profile is covered. The description adds valuable context: 'KV-cached (1h TTL)' and 'Handled env-aware in the MCP handler (needs the key + KV)' which inform the agent about dependencies and edge behavior. It slightly overstates infrastructure context but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, credit-worthy conciseness. The first sentence packs purpose and key behavioral context; the second covers requirements and tool composition. Slightly dense with references ('Phase III (FRC §7b)') but still efficient and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with complete schema coverage and strong annotations, the description covers purpose, key dependency (XAI_API_KEY), caching, and compositional context. It doesn't detail the return shape beyond field names, but without an output schema an agent still has enough to invoke correctly. Minor gap: not explaining what a matched chunk is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters. The description names 'content, score, file' as return fields but doesn't add new meaning about parameters beyond the schema. The baseline of 3 is appropriate since the schema carries the heavy lifting; the description adds only contextual framing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('semantic search'), a specific resource ('a Grok Collection'), and its edge/KV-cached characteristics. It also names the sibling it composes with (faf_section) for structural retrieval, distinguishing it from the structural sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use it ('Phase III (FRC §7b) — semantic search over a Grok Collection'), states a requirement (XAI_API_KEY secret), and names a complementary alternative (faf_section for structural retrieval, composing for hybrid). This gives clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faf_estimate_tokensEstimate tokensAEstimate token count for arbitrary content via the Zig WASM engine. Sub-millisecond, zero allocations. Useful for context-budget planning.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Content to estimate tokens for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only, idempotent, non-destructive behavior. The description adds meaningful extra context: sub-millisecond execution, zero allocations, and the underlying engine. This goes beyond the structured annotations and helps the agent anticipate performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences earn their place: the first states the action and object, the second adds unique behavioral and use-case context. There is no filler, and the most important information appears immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple single-parameter estimator, and the description covers its purpose, scope, performance, and use case. The output shape is not explicitly stated, but 'token count' strongly implies the return type. This is only a minor gap, so it is not a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter with full clarity: 'Content to estimate tokens for.' The description reinforces this with 'arbitrary content' but does not add new parameter-level semantics. With 100% schema coverage, the baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Estimate token count for arbitrary content.' This clearly distinguishes it from sibling tools like faf_analyze and faf_collections_search, which imply different operations. The mention of the Zig WASM engine further grounds the tool's identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Useful for context-budget planning' gives the agent a clear reason to select this tool. It does not explicitly call out alternative tools or exclusions, but the focused scope plus the sibling context is sufficient for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faf_gateFRC quality gate (promote/hold)APhase III (FRC) — pre-promotion quality gate. Scores .faf content (edge Mk4) + estimates tokens and returns a deterministic promote/hold verdict BEFORE it goes to a Grok Collection. Promote IFF score >= min_score AND tokens <= max_tokens (defaults 85/8000). Edge parity with the local gate; the hold-hint can't list empty slots at the edge.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Raw .faf YAML content to gate. | |
| min_score | No | Minimum score to promote (default 85). | |
| max_tokens | No | Maximum tokens to promote (default 8000). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark the tool read-only and idempotent, and the description adds genuinely useful behavioral context: the verdict is deterministic, the thresholds are combined with IFF semantics, defaults are specified (85 and 8000), and the edge behavior contains a notable limitation about hold-hints not listing empty slots. This is meaningful operational detail beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and dense: phase label, resource, purpose, threshold rule, defaults, and edge caveat all fit into a few sentences with no filler. The most important decision logic appears early, which helps an agent parse the core behavior quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no output schema, it provides most needed context: what to pass, the verdict rule, defaults, and an edge-behavior warning. However, the exact return shape is not described beyond 'promote/hold verdict,' and the term 'hold-hint' remains slightly under-specified without a schema or further explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all three parameters, and the description enriches that by adding default values and the exact condition under which a promote verdict is decided. It does not expand each parameter individually, but with full schema coverage the additional semantics are enough to invoke the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (.faf content), what the tool does (scores it, estimates tokens, and returns a promote/hold verdict), and where it sits in the pipeline (pre-promotion quality gate before a Grok Collection). The combined scoring-and-gating role differentiates it from siblings like faf_score and faf_estimate_tokens, even without naming them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage context and trigger: invoke this before content goes to a Grok Collection, with promotion contingent on both thresholds. It does not explicitly name alternatives to use instead when only scoring or only token estimation is needed, so it lacks explicit exclusions but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faf_get_tierGet tier for a scoreAResolve the FAF tier for a given numeric score. Returns the tier symbol (Trophy/Gold/Silver/Bronze/etc.) per the canonical tier-table.
| Name | Required | Description | Default |
|---|---|---|---|
| score | Yes | Numeric score 0-100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context on the return format (Trophy/Gold/Silver/Bronze) and references the canonical tier-table, which is not deducible from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the core action, the second clarifies the return symbol and the reference table. Each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, deterministic lookup with 100% schema coverage and no output schema, the description fully covers purpose, input, output, and underlying reference. The missing thresholds are not essential for invoking the tool correctly, as the tool itself resolves them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the input schema already describes 'score' as a number 0-100. The description merely repeats that it is a numeric score without adding threshold details, boundary behavior, or other semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Resolve'), the resource ('FAF tier for a given numeric score'), and a concrete return value ('Returns the tier symbol'). It clearly distinguishes itself from sibling tools like delta_check and faf_analyze, which serve different functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: when an agent has a numeric score and needs its canonical tier symbol. It does not explicitly mention alternatives or exclusions, but the sibling tool names are sufficiently distinct that no competing tool appears to offer the same function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faf_memoryPortable structured memory (.fafm)APhase III (FRC) — query the durable .fafm model by type/tag/priority/text. Omit filters for a structured summary. .fafm is NOT scored: this SELECTS facts (provenance preserved), never grades them.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Filter by a tag. | |
| type | No | Filter by fact type (e.g. "feedback"). | |
| query | No | Case-insensitive substring match on fact text. | |
| content | Yes | Raw .fafm YAML content. | |
| priority | No | Filter by priority (e.g. "critical"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, idempotent=true, and destructive=false, so the description does not need to carry the mutation-safety burden. It adds genuinely useful extra behavior: it states that facts are selected with provenance preserved, not graded, and that memory is durable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and every sentence contributes: querying, summary behavior, and the explicit non-scoring distinction. The 'Phase III (FRC)' prefix is slightly specialized jargon, but it is short and does not obscure the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the parameters are well-documented in the schema and the annotations cover safety, the description provides enough behavioral context: what to query, how to broaden or narrow, and what the operation intentionally avoids. There is no output schema, and the return structure is only vaguely described as 'structured summary,' but this is acceptable for a read-only query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% parameter descriptions, so this dimension starts at baseline 3. The description restates the filter dimensions and adds that omitting filters produces a structured summary, but it does not add new semantic information about the content parameter or the filter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb ('query') and resource ('.fafm model') and lists the four filter dimensions (type, tag, priority, text). It directly contrasts itself with scoring tools ('NOT scored... never grades them'), making its role unmistakable and separating from the sibling tool faf_score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear context: omit filters to return a structured summary or apply any of the four filters for a targeted lookup. It does not explicitly enumerate sibling alternatives, but the 'NOT scored' warning tells an agent not to treat this as the grading action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faf_orchestrate_recommendationOrchestrate Context Recommendation (FAF)ATakes raw content strings (.faf, .fafm, and optionally package.json/CHANGELOG.md/README.md) and runs deterministic drift + contradiction signals across the FAF substrate. Returns a structured Recommendation (recommend, severity, reason, summary) with hints containing the current effective_policy and partial[] for any stateful signals unavailable on the current surface. Light-lane execution (hosted) is WASM-pure with no filesystem access. Heavy-lane execution (local via bunx/rust-faf-mcp) has full FS + persisted state. Advisory only — never auto-fires.
| Name | Required | Description | Default |
|---|---|---|---|
| faf | No | Raw .faf YAML content (project DNA). Required for any meaningful analysis. | |
| fafm | No | Raw .fafm YAML content (memory layer). Enables drift detection. | |
| readme | No | Raw README.md content. Enables README arch-tree cross-stamp checks. | |
| changelog | No | Raw CHANGELOG.md content. Enables changelog cross-stamp checks. | |
| packageJson | No | Raw package.json content. Enables version cross-stamp checks (.faf vs pkg). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this read-only, idempotent, and non-destructive, and the description adds genuinely valuable behavioral context: hosted execution is WASM-pure with no filesystem access, local execution has full FS and persisted state, and the tool is advisory-only and never auto-fires. This clearly exceeds what the annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence in the description carries useful information: core behavior, output shape, execution-lane constraints, stateful-signal caveats, and safety semantics. It is dense but not bloated, and the most decision-relevant information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema available, the description compensates by defining the Recommendation shape and the hints fields. It also covers execution environments, state availability, and safety posture, making this definition sufficiently complete for an agent to understand the tool's contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the input schema already documents each parameter meaningfully. The description lists the accepted file types and frames them as inputs to drift/contradiction analysis, but it does not add substantial parameter behavior beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb-resource relationship: it takes raw content strings, runs deterministic drift/contradiction signals, and returns a structured Recommendation. It is clearly legible and unlikely to be confused with a vague system tool, though it does not explicitly distinguish itself from closely related siblings like faf_analyze or faf_gate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by describing its orchestrated recommendation role and advisory nature, but it never explicitly says when to prefer this over alternatives. With 19 sibling tools, the absence of direct sibling positioning leaves the agent to infer the right selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faf_scoreScore .faf contentAScore .faf YAML content via the Mk4 Zig-WASM engine. Returns 0-100 (capped). Same engine as xai-faf-rust + xai-faf-zig (parity-tested). Sub-ms at the edge.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Raw .faf YAML content. Souls with a [faf] section have it extracted automatically. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral facts beyond those: the result is capped at 0-100, the engine is parity-tested with other implementations, and sub-ms performance is expected. The schema shows automatic [faf] section extraction, adding further context. No contradictions with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core action comes first, followed by the output range and notable behavioral facts. No sentence is redundant or filler. It is concise without underspecifying.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one required parameter, read-only annotations, and no output schema, the description covers the primary essentials: the input is .faf YAML content, the result is a 0-100 score, and the operation is safe/idiomic because annotations provide the safety profile. It could detail the return payload shape, but 'Returns 0-100' is enough for most calling scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the parameter's own description already explains 'Raw .faf YAML content' and auto-extraction of [faf] sections. The tool description does not add additional parameter-level semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Score') and a specific resource ('.faf YAML content'), then states the exact output range ('Returns 0-100 (capped)'). This clearly defines what the tool does and differentiates it from sibling tools like faf_analyze or faf_validate, which are about analysis/validation rather than numerical scoring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool instead of its siblings such as faf_analyze or faf_validate. The mention of xai-faf-rust and xai-faf-zig is about engine parity, not usage context or alternatives. Only an inferred use case—scoring .faf content—is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faf_sectionStructure-aware retrievalAPhase III (FRC) — returns an EXACT, WHOLE .faf section by dotted path (e.g. "stack", "human_context"), structure preserved — the deterministic complement to blind chunking. Omit "section" to list every path.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Raw .faf YAML content. | |
| section | No | Dotted path to retrieve (e.g. "stack.backend"). Omit to list all paths. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by revealing that the returned section is exact, whole, structure-preserving, and deterministic. It also documents behavior when 'section' is omitted (lists every path). These are valuable behavioral details not present in readOnlyHint or idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extraordinarily efficient: two sentences, front-loaded with the key return behavior plus deterministic positioning and the output-variation behavior ('omit section to list every path'). There is no filler or redundant rewording of schema labels.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters, one required, a full schema, and rich annotations, the description explains what it returns, how to use it, and the exception behavior when the optional parameter is omitted. No significant gap remains that a caller would need to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both the 'content' and 'section' parameters thoroughly. The description adds minimal new parameter-level detail, though it offers additional examples ('stack', 'human_context') beyond the schema's 'stack.backend' example. Thus baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'returns' with a clear resource: an 'EXACT, WHOLE .faf section by dotted path'. It also gives concrete examples ('stack', 'human_context') and distinguishes itself as 'the deterministic complement to blind chunking', making it easy to tell apart from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Phase III (FRC)' and positions itself as a deterministic complement to blind chunking, which gives helpful context on when to use it. It does not explicitly call out when not to use it or name an alternative tool, so this is clear guidance without explicit exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faf_validateValidate .faf contentAValidate .faf YAML content via the Mk4 Zig-WASM engine. Returns true if mission-ready (>= 100).
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Raw .faf YAML content to validate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, idempotentHint=true, destructiveHint=false, lower the bar. The description adds genuine context: it names the underlying engine (Mk4 Zig-WASM) and, critically, defines the success threshold ('true if mission-ready >= 100'), which tells the agent what a positive result means. It stops short of describing failure mode on malformed YAML (throw vs. false), but the added value is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero redundancy. The first sentence states the operation and engine; the second states the return semantics with the exact threshold. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only, idempotent tool with a well-described return condition, this is nearly complete. The only gap is the failure mode for syntactically invalid YAML when the engine score is undefined. An agent can call and interpret results correctly with what's given.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — the schema fully describes 'content' as the raw .faf YAML content. The description reinforces that it's YAML and adds the engine/threshold context, but adds no per-parameter semantics beyond that. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('validate') with a specific resource ('.faf YAML content') and clarifies the engine used. It adds meaning by defining what 'valid' means — mission-ready, score >= 100 — which goes beyond the tool name and title. It doesn't explicitly contrast with sibling tools like faf_analyze, so it's not fully demarcated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use validation over analysis (faf_analyze), delta checks, or the various search/query siblings. The description tells how the tool behaves but gives the agent no explicit selection criteria, and no mention of 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.
generate_faf_from_githubGenerate FAF from GitHubAGenerate a .faf file from any public GitHub repository WITHOUT cloning. Extracts 6 Ws from README, analyzes stack from languages and package.json, and generates Championship-grade AI context. Returns .faf content, quality score, and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | GitHub repository URL or owner/repo format (e.g., "facebook/react" or "https://github.com/facebook/react") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and false destructiveHint. The description adds meaningful behavioral context beyond those hints: it does not clone, it extracts data from README, languages, and package.json, it generates a Championship-grade AI context, and it returns content plus quality score and metadata. No contradiction with the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at three sentences and front-loaded with the primary action. The only mild weakness is 'Championship-grade AI context', a promotional phrase that adds no precise behavioral meaning, but the overall density remains high and it does cover the key data points.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single parameter, no output schema, and relevant annotations, the description covers the prerequisites, the input form, the processing behavior, and the return fields (.faf content, quality score, metadata). It does not discuss error cases or network dependencies, but those are nonessential given the scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the repo parameter completely with format examples. The description supplements this by clarifying that the repository must be public—important operational constraints that would not be obvious from the schema alone. That lifts it above the baseline for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Generate'), a specific resource ('.faf file from any public GitHub repository'), and a distinguishing constraint ('WITHOUT cloning'). It tells the agent exactly what the tool produces, making it easy to separate from analysis, scoring, and validation sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the main scenario: create a .faf file from a public GitHub repo without cloning. However, it does not explicitly say when to choose this tool over siblings like faf_analyze, faf_validate, or generate_faf_from_github, nor does it provide exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_soulGet Context SoulBFetch a context soul by name. Returns structured AI context.
| Name | Required | Description | Default |
|---|---|---|---|
| soul | Yes | Soul identifier (e.g., "spacex", "wolfe", "grok") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare read-only, idempotent, and non-destructive behavior, so the description doesn't need to repeat that. It adds the fact that the tool returns 'structured AI context', but that is vague and doesn't explain the return format or failure behavior. No contradiction exists with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no waste. The core action is front-loaded, and the additional 'Returns structured information' sentence is concise and appropriately placed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup tool with read-only annotations, the description is essentially complete. The only notable gap is that 'structured AI context' is underspecified, but it's a minor omission given the simplicity of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear. The description doesn't add any meaning beyond the schema's existing documentation of the single 'soul' field, so it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource — 'Fetch a context soul by name' — and clearly establishes this as an exact lookup rather than a search or listing. It doesn't explicitly name or differentiate the sibling tools, but 'by name' does enough to convey the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus sibling tools like search_context or list_souls. The phrase 'by name' implies a direct lookup when the identifier is known, but there is no explicit statement about alternatives or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_soulsList Available SoulsBList all available context souls.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already convey that this is a safe, non-mutating read-only operation. The description adds no additional behavioral context beyond saying it lists, and it does not mention whether results are ordered, paged, limited, or filtered. With annotations covering the safety profile, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'List all available context souls.' It states the verb and resource concisely with zero wasted words, which achieves appropriate size and clarity for a zero-parameter list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with a trivial schema, the description nearly suffices. The only omission is clarifying what a 'context soul' is and how many of them might be returned, but given the tool's simplicity and the safety annotations, the definition is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and Baselines we set the baseline for a 0-parameter tool at 4. Although the description adds no parameter-specific semantics, the absence of parameters means there is nothing meaningful to document and the 100% schema description coverage (or equivalent) means nothing remains undocumented. This deserves the baseline 4 rather than a high parameter-related score since the description itself offers no parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'List all available context souls' which names a specific verb and resource, so it is clear about what the tool does. However, it does not distinguish this from sibling tools like list_tags or get_soul beyond the resource name, and 'context souls' is somewhat domain-specific jargon that may not be immediately informative without additional context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus siblings such as get_soul, list_tags, search_by_tag, or generate_faf_from_github. There is no mention of what 'context souls' means, nor any context indicating whether this is a discovery tool, a navigation tool, or a retrieval tool. An agent would have to infer usage from the tool name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_tagsList TagsAList all unique tags used in a soul, with counts.
| Name | Required | Description | Default |
|---|---|---|---|
| soul | Yes | Soul identifier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, idempotent, and non-destructive. The description adds the useful behavioral detail that tags are unique and counted, but it does not explain return structure, ordering, or any further edge-case behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One simple, front-loaded sentence states the action, resource, and result nuance. No filler or redundant wording; every part of the description earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, non-destructive listing tool, the description covers the core need. Since there is no output schema, 'with counts' provides some return-value context, though the exact response format is not stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already explains the 'soul' parameter. The description reinforces it by saying tags come from 'a soul', but adds little meaning beyond what the schema and tool name already provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List all unique tags used in a soul'. It also clarifies the result includes counts and highlights uniqueness, making it clearly distinct from sibling tools like search_by_tag or tag_intel.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to choose this over search_by_tag, tag_intel, or other sibling tools. The description implies its purpose but offers no exclusions, prerequisites, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
refresh_fafRe-ground on .faf content (drift → refresh → re-grounded)ARe-ground on .faf content — re-score via the Mk4 Zig-WASM Enterprise scorer (33-slot, honors the authored app-type shape), report drift vs an optional baseline score, and return a stamped re-ground. The explicit re-grounding primitive for long sessions: drift → refresh → re-grounded. Built for Grok, by request.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Raw .faf YAML content to re-ground on. | |
| baseline | No | Optional last-known score (0-100). When provided, the drift delta (current - baseline) is reported. | |
| verbatim | No | When true, return the full .faf content verbatim with the stamp. Default false (stamped delta + summary). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already covering read-only, idempotent, and non-destructive behavior, the description adds useful context: re-scoring via the Mk4 scorer, honoring the authored app-type shape, optional drift delta, and stamped vs verbatim output. It could be clearer about exactly what the 'stamp' contains, but the annotations do not carry that burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is dense and informative, but the second sentence partly repeats the title and process, and the final 'Built for Grok, by request' adds no operational value. The description remains compact but not every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently sketches the shape for both default verbatim and non-verbatim mode: stamped delta+summary vs full content verbatim plus stamp. It supports agent deciscion-making on when to call it in long sessions, and the schema and annotations cover the remaining invocation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter descriptions are already clear about content, baseline drift, and verbatim mode. The tool description mostly rephrases those concepts without adding deeper semantics, which is acceptable at the baseline for fully documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific operation: re-ground on .faf content, re-score via a named scorer, report drift against baseline, return a stamped re-ground. The 'explicit re-grounding primitive for long sessions' differentiates it from a plain first-time scoring tool and from the sibling search/analysis tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear 'when' — any long session where drift needs to be reset via refresh/re-ground. It does not name alternative tools or say when not to use it, so it stops short of explicit when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_by_tagSearch by TagAFind all entries in a soul with a specific tag.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | Tag to search for | |
| soul | Yes | Soul identifier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate that the tool is a read-only, idempotent, non-destructive operation, so the description does not need to cover those safety aspects. It adds only a minor behavioral detail: the result set includes 'all entries'. It does not describe pagination, result ordering, potential error conditions, or output format. Since annotations carry the main behavioral burden, a mid-range score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed, front-loaded sentence with no unnecessary text, filler, or repetition. Every word contributes meaning: action, scope, resource, and parameter. It is concise while remaining clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool with strong annotations, the description is close to complete. It clarifies the target of the search and the namespace ('soul'), and the input schema fills the details. The main gap is that it does not specify what an 'entry' looks like in the response or how results are formatted; since there is no output schema, slightly more context about the return shape would have been helpful. Overall it is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both 'soul' and 'tag' (100% known coverage), so the description does not need to re-explain them. The description adds no further detail about default values, enum constraints, format requirements, or edge-case behaviors. This matches the baseline of 3 for a fully documented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb and resource combination: 'Find all entries in a soul with a specific tag.' It identifies the main input (soul and tag) and the goal, and it is not a tautology of the tool name. It does not explicitly differentiate from sibling tools, but the wording is specific enough for an agent to infer the tool's job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its intended use: when you need to find entries with a specific tag in a soul. However, it gives no explicit guidance on when not to use it, nor does it mention alternatives like search_context or list_tags. The 'when to use' information is indirect rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_contextSearch ContextAFull-text search across souls. Returns matching lines only (token-efficient).
| Name | Required | Description | Default |
|---|---|---|---|
| soul | No | Specific soul (optional, searches all if omitted) | |
| query | Yes | Text to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation read-only, idempotent, and non-destructive, and the description is consistent with that. It adds useful behavior beyond annotations by revealing that results are line-only and token-efficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences carry all the essential information, with the primary action front-loaded. Every phrase earns its place, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema, annotations, and description together provide a solid operational picture: what is searched, what is returned, and that the operation is safe. Minor details such as pagination, result limits, or case sensitivity are absent, but they are optional rather than critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters thoroughly, with 100% coverage. The tool description does not add new parameter-level semantics, so it stays at the schema-driven baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Full-text search across souls', a specific verb and resource that is instantly clear. The next sentence, 'Returns matching lines only', distinguishes it from sibling tools like search_by_tag or get_soul by declaring its result shape.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes a clear use case: full-text content search across souls, with a token-efficient return option. It does not explicitly name alternatives or say when not to use it, but the context is specific enough for an agent to infer the intended invocation scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tag_intelTag IntelADiscover tag patterns, co-occurrence, candidates, and merge suggestions across all namepoints. Optionally suggest tags for a specific handle.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | No | Optional: suggest tags for this specific namepoint |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which already cover the safety profile. The description adds behavioral context about the tag discovery and suggestion capabilities, but does not disclose details like return format, volume of results, or any additional side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads the primary purpose (tag pattern discovery), and quickly mentions the additional suggestion feature. It uses an efficient two-clause structure with no redundant or overly verbose information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter, no output schema, and annotations that define the safety profile, the description is mostly complete. The main gap is it does not specify the output format or how results are returned, such as whether suggestions include confidence scores or structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter schema covers the handle parameter with a description, achieving 100% schema description coverage. The tool description mentions optional tag suggestions for a specific handle, which supplements the schema. However, it does not add deeper meaning beyond the schema's own description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: discovering tag patterns, co-occurrence, candidates, and merge suggestions across all namepoints. It also mentions an optional behavior (suggesting tags for a specific handle), which adds another clear capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when tag-related analysis or suggestions are needed—and the optional handle parameter provides context for a specific use case. However, it does not explicitly state when NOT to use this tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Sign in to create a connector for this server.