Product action (do surface): submit a project inquiry with name, email, and a brief. Use sandbox=true to avoid a real handoff.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| Yes | |||
| message | Yes | ||
| sandbox | No | ||
| projectId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly=false, idempotent=false, and destructive=false, lowering the burden on the description. The description adds useful sandbox behavior, but it does not disclose what a real handoff entails, such as external notifications or record creation.
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 sentences and front-loads the action and core fields. The minor jargon 'do surface' prevents a top score, but overall it is efficient.
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 five parameters, no output schema, and zero parameter descriptions, the description omits projectId, the behavior when sandbox=false, and any return/error details. It is minimally sufficient for a basic call but not robust enough for confident agent decision-making.
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 0%, so the description must compensate for all five parameters. It only clarifies that message is the 'brief' and mentions sandbox usage; projectId is completely undocumented, and no format or validation hints are given for name or email.
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 names a specific verb (submit) and resource (project inquiry) and identifies the core payload (name, email, and a brief). It is distinguishable from the fetch/list/search siblings as a write-style product action, though the phrase 'do surface' is somewhat opaque.
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 one concrete usage directive: use sandbox=true to avoid a real handoff. However, it does not explicitly state when to choose this tool over sibling tools or any preconditions, leaving usage context mostly implied.
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.