io.github.seer22/shturman-direct-mcp

by seer22

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation5/5
Each tool targets a distinct operation or API: status, Wordstat, Direct read/plan/apply/report, media attach, and separate Metrika and Audience read/write pairs. The two-phase plan/apply design and explicit credential separation make misselection unlikely.
Naming Consistency4/5
All tools share the direct_ prefix and snake_case, which gives the set a recognizable family resemblance. However, the second part mixes nouns, verbs, and domain suffixes—read/plan/apply versus status/wordstat/metrika_goals—so it is not a strict verb_noun pattern.
Tool Count5/5
11 tools is well within the appropriate range for a server spanning Direct, Wordstat, Metrika, and Audience. Each tool covers a broad surface—direct_read alone handles all reading methods—so none feels redundant or superfluous.
Completeness3/5
The set provides read, write, report, and media paths across several APIs, and the direct_plan/direct_apply pattern covers arbitrary Direct writes. However, starting ads and unarchiving are explicitly absent, and Audience/Metrika writes are limited to one goal type and one geo-segment path, leaving notable lifecycle gaps.
Average 4.6/5 across 11 of 11 tools scored. Lowest: 4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- Last stable release on September 1, 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

Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, and idempotent. To that the description adds effective non-annotation behavioral context: reports cost no API units, the tool checks the requested period and refuses requests past the rolling three-year boundary instead of returning a silently cut subset, and dates are explicit so the same request remains stable. No contradiction with annotations; this goes well beyond the structured hints.
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 reasonably concise and front-loads the core purpose in the first sentence. The second paragraph is longer but earns its place by warning about the exact boundary behavior, which is critical for correct invocation. It could be slightly tighter, but every part contributes meaningfully.
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 covers the most important behavioral caveat and the cost advantage, and the schema covers several parameters. However, there is no output schema and the description does not describe what the returned rows look like, nor does it clarify several parameters such as filters, name, or include_vat. For a tool with 9 parameters, this is functional but not fully 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 description coverage is 67%, so the schema already handles many parameters such as date formats, fields examples, report_type examples, and client_login behavior. The description adds general date semantics ('Dates are explicit rather than relative') and the period-boundary rule, but it does not explain underdocumented parameters like name, filters, or include_vat. This is adequate but not a strong compensation for the remaining gaps.
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 states the verb and resource: 'Ask for a report and get its rows.' It identifies the tool as a report-generation operation and distinguishes it at a high level from object calls by emphasizing that reports return prebuilt rows and cost no API units. It does not explicitly name a sibling tool, but the purpose is still specific and actionable.
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 for when to use the tool: when you need report rows rather than rebuilding numbers from object calls, since reports are cheaper. It also explains the date boundary behavior, telling the agent that requests reaching past available statistics will be refused rather than silently truncated. It does not explicitly enumerate alternatives or exclusion conditions, so it stops short of a full 5.
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?
Adds substantial behavioral context beyond the annotations: changes a live advertising account, sandbox is off by default, no transactionality, and partial-state failures are reported. Also discloses absent capabilities. No contradiction 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by critical side effects and limitations. Each sentence earns its place; minor redundancy like 'the tool says so' is acceptable but not maximally crisp.
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?
Covers purpose, inputs, real-world mutating effects, failure behavior, and unsupported operations. It does not describe the response format, but for an action-oriented tool with no output schema the missing return-value detail is a relatively minor gap.
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 both parameters already described in the input schema. The description reinforces that only the plan ID and confirmation phrase are accepted, but it does not add meaningful semantic detail beyond what the schema provides.
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 a specific verb and resource: 'Perform the calls of a plan made earlier.' It is easily differentiated from siblings like direct_plan (which creates the plan) and read-only tools like direct_read or direct_status, and it explicitly notes what it cannot do (start ads or unarchive).
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 this tool should be used after a plan has been made earlier and clarifies its limited scope ('and nothing else'). It also states exclusions (cannot start ads or unarchive), though it does not name specific alternative sibling tools for those actions.
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 substantial behavior beyond the annotations: radius units are 'proven by a two-sided probe', limits are 'bought by a live refual', and the service's wrapper refual 'masks every other complaint'. It also explains preview behavior without confirmation and that the segment appears under a DIFFERENT number after processing.
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 front-loaded with purpose and every paragraph covers a distinct concern: scope, limits/validation, and post-create verification. It is longer than minimal but the density of operationally valuable detail justifies the length, though some provenance details like 'two-sided probe' could be trimmed.
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 no output schema, the description explains what to expect: a preview without confirmation, a confirmation phrase, and a post-create readback with status and a different number. It also covers point limits, radius bounds, and condition requirements, leaving no critical gap for invoking the tool correctly.
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 reinforces radius units in METERS and that condition requires both period_length and times_quantity, but does not add significant meaning beyond the schema's own parameter 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 opens with a specific verb and resource: 'Create ONE geo segment in Yandex Audience from CIRCLES'. It explicitly distnguishes the tool from polygons by stating they are 'deliberately not implemented', making the tool's scope unmistakable.
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 gives clear context for when to use the tool: the live measured create path from circles, not polygons, and when 'condition' segments require extra parameters. It also advises verification after creation via reading retargetinglists, but does not explicitly name sibling tools as alternatives, so it falls just short of full 1.
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 adds substantial behavioral context beyond the annotations: the three-step video flow, the fact that every step reports success independently, the undocumented requirement to resend headlines/texts when updating an ad, the tool's behavior of reading the ad first, its avoidance of a legacy collapsing field, and its post-operation readback. No contradiction with annotations exists.
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 front-loaded with the core purpose and then uses each subsequent paragraph to explain non-obvious behavior that materially affects how an agent invokes the tool. The length is justified by the complexity of the operation, and there is no filler or repetition that weakens it.
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 multi-step mutation with no output schema, the description covers the workflow, hidden API requirements, safety around the legacy field, and the final headline-count readback. The main gap is that the 'confirmation' parameter is not explained in context—an agent still does not know when a refusal occurs or when confirmation must be supplied.
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 per-parameter detail: it clarifies that images and videos are local path-based files, but it does not explain when 'confirmation' would be needed or what triggers the refusal. The schema already carries most of the parameter meaning.
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 a specific verb and resource: 'Attach local images or videos to an existing ad'. It also distinguishes the tool by saying it does 'the whole chain rather than one call', so an agent can tell this is a high-level composite operation rather than a single upload/update call.
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 intended use is clear from the opening sentence: use this tool when attaching local media to an existing ad. It explains that videos require a three-step chain and that this tool handles it in one call, which implicitly guides an agent away from doing separate upload/create/attach calls. It does not name explicit alternative tools or exclusions, so it stops short of 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?
Beyond the readOnly and idempotent annotations, the description adds that the tool exposes limitations ('what it will not do') and reports how fresh the information is ('when it was measured'). This is useful behavioral context and does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences front-load the core meaning ('Where things stand') and then enumerate the report's scope. There is no filler, redundancy, or unnecessary detail.
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?
For a zero-parameter, read-only status tool, the description is complete: it says why to call it, what it covers, and what limits it will communicate. The annotations already cover safety, so no additional behavioral detail is required.
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 input schema has zero properties, so there are no parameter semantics to explain. The description appropriately focuses on what information the tool returns rather than parameters.
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 what the tool reports: configured credentials, what the server knows, when it was measured, and what it will not do. This distinguishes it from the action-oriented sibling tools such as direct_read and direct_apply.
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 instructs the agent to call this first in a session, before anything is attempted. It establishes a clear usage context, though it does not name alternative tools or specify 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses non-obvious behavioral traps: accuracy=full is forced because the service default is SAMPLING, data lags about 2 hours and the current day is underfilled, and the tool needs its own Metrika credential rather than the Direct one. This is exactly the context annotations cannot convey.
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 front-loaded and each section earns its place with practical warnings. It is slightly redundant with the schema's date2 and action descriptions, but the critical caveats justify most of 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?
For a three-action API with 8 parameters and no output schema, the description provides the essential surrounding context: authentication, read-only scope, sampling behavior, data lag, and the write alternative. Combined with the detailed schema, an agent has enough to select the right action and call it correctly.
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 main description mostly restates what the schema already says, such as action meanings, ym:* names passed through as written, and the date window advice. The accuracy=full detail is valuable but functions more as behavioral context than a parameter-semantics addition.
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 title and first sentence define the tool as 'The Yandex Metrika API, reading only' with three explicit actions. It clearly distinguishes the read scope from the write sibling direct_metrika_goals, so an agent can tell this tool apart immediately.
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?
The description gives concrete per-action guidance, warns to end date windows yesterday because of the 2-hour data lag, and explicitly says creating goals is a write that belongs in direct_metrika_goals. It also explains the separate credential requirement, leaving little ambiguity about when and how to use the tool.
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?
Beyond the annotations, the description discloses the idempotency check by event identifier, the read-back validation with explicit error semantics, the preview behavior, and the confirmation phrase safety mechanism. These are meaningful behavioral details that annotations alone do not provide.
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 front-loaded with the core operation and every subsequent sentence adds distinct value: idempotency behavior, read-back validation, timing warning, preview behavior, and confirmation safety. No sentence is wasted.
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?
For a tool with no output schema, the description clearly explains both preview output and error semantics after read-back. Combined with full schema coverage and annotations, an agent has enough to select and 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 useful semantics for confirmation (preview without it, and it names the counter) and for counter (numeric id), which improves parameter understanding 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 opens with a specific verb and resource: "Create JavaScript-event goals in one Metrika counter." It further distinguishes itself from siblings by emphasizing idempotent creation of only missing goals, which is unique among the direct_* family.
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 operational context: goals must exist before the first ad click, and calling without confirmation yields a preview. It does not explicitly name alternatives or when-not-to-use, but it supplies enough context for an agent to recognize when this tool applies.
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?
Annotations already mark readOnlyHint: true, but the description adds substantial behavioral context beyond that: 'Nothing is sent,' the plan costs units, and a write plan must include read-back verification because 'a successful response does not prove the outcome in this API.' This goes far beyond what annotations alone convey.
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 front-loaded with the core purpose, then gives usage direction, then addresses a critical verification caveat. Every sentence contributes meaningful guidance without redundancy or filler.
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?
The description is complete for a tool with no output schema and only three parameters. It explains the returned identifier, the planning-only behavior, the cost disclosure, and the verify requirement, so an agent has enough context to select and invoke it correctly.
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 reinforces the purpose of 'calls' and emphasizes the 'verify' requirement, but it does not add significant parameter-level details beyond what the schema already states.
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 a specific verb and resource: 'Turn a list of intended API calls into a plan and return its identifier.' It clearly states the tool's non-executing nature with 'Nothing is sent,' and contrasts itself with direct_apply, making sibling differentiation explicit.
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?
The description explicitly says 'Use this for every change' and explains why direct_apply cannot be used for raw requests because it 'accepts only an identifier and has no parameter for a request body.' It also gives conditional usage guidance: plans that write must carry 'verify' calls.
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?
Beyond the readOnly/openWorld/idempotent annotations, the description adds critical behavior: each call spends real money from the cloud folder, exact costs per method, tree is free, quota is 100 calls per sliding hour, quota is reserved locally before the network call, and exhaustion returns a named wait. This is genuinely valuable 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 dense but every sentence earns its place: source and methods, cost and quota warning, and credential setup. No filler; the most important operational warnings are front-loaded and bolded.
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?
For an expensive, quota-limited, 8-parameter tool with no output schema, this description is complete enough: it explains method-specific return concepts, costs, quota behavior, credential prerequisites, and a safe free first call. Combined with the rich schema, an agent has what it 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.
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 prose repeats method outcomes that the schema already describes and does not add parameter-level meaning beyond what the schema provides. The schema already documents region codes as strings, date formats, device limits, and num_phrases bounds.
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 identifies the Wordstat API (Yandex Search API v2, Yandex Cloud) and explicitly distinguishes it from the Direct API. It lists four concrete methods with different purposes, so an agent knows exactly what the tool does and how it differs from the direct_* siblings.
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?
It says when to use the tool (search demand), which method to start with (tree, free and safe), warns about real-money costs, and explains the separate credential requirement. It also explicitly states this is not the Direct API, giving a clear exclusion versus sibling tools.
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?
Annotations already mark readOnlyHint, but the description goes well beyond by explaining that only processed segments are visible, that IDs differ from Audience ids, that no_data=true means counting is incomplete, and that totals live in the stat response rather than the segment object. These are non-obvious behaviors an agent needs to interpret results correctly.
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 dense but every sentence carries essential information: action semantics, tricky data-status behavior, ID mismatch warning, credential requirements, and sibling routing. It is front-loaded with the core purpose and reads in a logical flow without filler.
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 sufficiently explains the return semantics for both actions, including status values, no_data behavior, and where totals live. It also covers prerequisites, credentialing, and the alternative tool for writes, making the definition complete for correct selection and invocation.
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?
Input schema coverage is 100% with enum and descriptions for both parameters, so the baseline responsibility is already met. The description adds meaningful context by clarifying what each action does with the parameters and explaining that stat requires segment_id and that totals appear in the stat response, not the segment object.
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 names the API, states it is read-only, and enumerates two actions with specific verbs: 'segments' lists segments and 'stat' answers reach/affinity. It also distinguishes itself from the write sibling direct_audience_segments, so an agent can immediately tell what this tool is and is not.
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?
The description clearly states when to use the tool: for reading audience segments and stat data. It explicitly routes the write case to direct_audience_segments, warns that retargeting conditions should be verified via retargetinglists rather than computation, and provides the required credential setup command.
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?
Beyond the readOnlyHint and idempotentHint annotations, the description discloses that cost is checked before the call, that state-changing calls are refused, and that some read methods return misleadingly empty-looking results without the right field names. It also flags return-type quirks for specific methods.
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?
Every sentence earns its place: the core call pattern and write exclusion come first, followed by cost semantics and known traps. It is dense but well organized, with no repetition of schema fields or annotation details.
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?
For an open-world read wrapper with no output schema, the description covers invocation, refusal behavior, cost semantics, and the most common empty-result traps. It also tells the agent to read knowledge://traps first, which is the right pre-flight step for this 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?
The input schema already covers all four parameters at 100%, so the baseline is 3. The description adds value by giving dotted method examples such as keywordsresearch.hassearchvolume, extra service names like dictionaries, and clarifying the meaning or shape of results for those calls.
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 calls any reading method of Direct API v501, gives concrete examples like campaigns.get, ads.get, and keywords.get, and distinguishes itself by refusing state-changing operations. It clearly separates this tool from write-capable siblings.
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?
It provides a clear when-to-use rule: call it for any reading method. It also gives an explicit when-not-to-use rule: state changes go through direct_plan and direct_apply. The pointer to knowledge://traps before use is additional concrete guidance.
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:

[![shturman-direct-mcp MCP server](https://glama.ai/mcp/servers/seer22/shturman-direct-mcp/badges/card.svg)](https://glama.ai/mcp/servers/seer22/shturman-direct-mcp)

Score Badge

Copy to your README.md:

[![shturman-direct-mcp MCP server](https://glama.ai/mcp/servers/seer22/shturman-direct-mcp/badges/score.svg)](https://glama.ai/mcp/servers/seer22/shturman-direct-mcp)

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/seer22/shturman-direct-mcp'

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