Product action (do surface): mint a free kwnva.design API key for attributed writes and sandbox tests. No payment and no waitlist.
| Name | Required | Description | Default |
|---|---|---|---|
| client_name | No | Optional name for the agent or integration |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/destructive/idempotent hints; the description adds meaningful behavioral context by stating the key is free, requires no payment or waitlist, and is scoped to attributed writes and sandbox tests. It 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The substantive content is delivered in two short sentences with the key facts front-loaded. The 'Product action (do surface)' prefix is largely redundant and prevents a 5, but it does not obscure the actual guidance.
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 tool with one optional parameter and no output schema, the description conveys the action, purpose, and zero-friction prerequisites. It could be more explicit about the returned artifact, but 'mint an API key' sufficiently implies the key is the result.
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% – client_name is already documented as an optional name for the agent or integration. The description adds no additional parameter-level meaning, so the 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?
The description states a specific verb ('mint') with a concrete resource ('a free kwnva.design API key') and a clear purpose ('attributed writes and sandbox tests'). This clearly distinguishes it from the sibling read/query/inquiry 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 gives clear context for when to use it: when a free API key is needed for attributed writes or sandbox testing, with no payment and no waitlist. It does not explicitly name alternatives or exclusions, but the sibling tools are unrelated, so the context is sufficient.
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.
The read tools are mostly distinct: fetch returns one project by id, list provides paginated browsing with category filters, and search queries by multiple fields. There is some overlap between list_portfolio_projects and search_portfolio_work when both are used for category filtering, but the descriptions are clear enough for an agent to choose appropriately.
All tool names follow a consistent snake_case verb_noun pattern: fetch_*, list_*, search_*, mint_*, submit_*. The style is uniform and predictable, even though the nouns for case studies vary slightly between project, portfolio, and work.
Six tools is a well-scoped size for a portfolio server. The core reading and searching operations are covered, and the two product actions (API key minting and project inquiry) add clear interaction value without bloating the surface.
The server covers the main portfolio use cases: listing projects, searching work, retrieving individual case study details, and fetching studio profile information. It also includes contact and API key actions, so there are no obvious dead ends or missing operations for the stated purpose.