Poll for device authorization completion. Returns "pending" (keep polling every 5s), "approved" (with api_key and tier), or "expired" (start over with mcpAuth).
| Name | Required | Description | Default |
|---|---|---|---|
| deviceCode | Yes |
Changes observed during successful MCP inspections. Dates show when Glama detected each change.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of explaining behavior. It discloses the three possible return states ('pending', 'approved', 'expired') and associated outcomes (api_key and tier on approval). It also gives operational guidance (polling interval and recovery action). It does not mention error handling for invalid device codes, but the key behavioral traits are covered.
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 extremely concise: two sentences total. It front-loads the primary action ('Poll for device authorization completion') and then lists the return values and resulting actions. Every sentence earns its place with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers the main behavioral aspects: return statuses, polling interval, and next steps. It does not detail error cases (e.g., invalid deviceCode) or exact structure of api_key/tier, but for a poll tool this is reasonably complete. The lack of an output schema makes the return value explanation essential, and it is provided.
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 one parameter (deviceCode) with 0% schema description coverage, so the description must compensate. It does not explicitly describe what deviceCode is, where it comes from, or format requirements. The context implies it comes from mcpAuth, but this is not stated directly. The description adds minimal value beyond the schema parameter name.
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 with a specific verb ('Poll') and resource ('device authorization completion'). It explains the three possible outcomes, which makes the tool's function unambiguous. However, it does not explicitly differentiate from the sibling tool 'deviceAuthPoll', which may have similar functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: poll every 5 seconds while pending, and start over with mcpAuth on expiry. It implies the tool is part of a device authorization flow. It does not explicitly state when not to use it or compare it to the similar sibling 'deviceAuthPoll', but the guidance given is actionable and useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Most tools have clear, distinct purposes: parse, convert, estimate, formats, auth, auth-poll, account, upload, and feedback. The main ambiguity is that editDocument with an empty delta array behaves like a parse, overlapping with mcpParse.
Seven tools share a useful mcp prefix with PascalCase, but editDocument and getUploadUrl are camelCase and submit_feedback is snake_case. The casing and verb-style inconsistencies make the tool set feel less coherent than its overall design suggests.
Ten tools is a well-scoped size for this domain: authentication, account, upload, formatting, estimation, parsing, editing, conversion, and feedback are each represented. No tool feels redundant or like filler.
The surface covers the key parse workflow: get an API key, upload, estimate, parse, edit, convert, and check supported formats. Minor gaps exist, such as no explicit API-key revoke action and some output/workflow steps being delegated to the SDK/CLI.
