portfolio_list_projectsAll projects by Marian Matinca (AI Adoption Lead, Bucharest): id, title, category, one-line result, tags, live site. Call portfolio_get_project with {id} for full details.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Content language (all content exists in both en and ro) | en |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true, which the description does not contradict. The description adds behavioral context by specifying the return fields and the author/owner of the data, providing useful information beyond 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 extremely concise, consisting of two sentences with no wasted words. The most important information (what the tool returns) is front-loaded, and the follow-up suggestion is placed at the end. 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 that there is no output schema, the description explicitly lists all fields returned (id, title, category, one-line result, tags, live site), which is complete for a listing tool. The single optional parameter is fully described in the schema, and the description provides context about the data source (Marian Matinca) and a clear next-step suggestion. No gaps are present.
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 covers the single parameter (lang) fully with a description and enum values (ro, en). The description does not repeat or add any parameter semantics beyond what the schema already provides, so a baseline score of 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 clearly states the tool lists all projects by Marian Matinca with specific fields (id, title, category, one-line result, tags, live site) and contrasts with portfolio_get_project for full details. This specific verb+resource+scope makes its purpose unmistakable and distinguishes it 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 provides clear context by naming the author and location, and explicitly suggests calling portfolio_get_project for full details. It implies this tool is for summaries while the other is for details, but does not explicitly state when to avoid using this tool or describe alternative scenarios.
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.
Each tool has a clear and distinct purpose: listing vs. getting details for blog posts and projects, retrieving the profile, and performing a cross-domain search. No two tools overlap in functionality.
All tool names follow a consistent portfolio_<verb>_<noun> pattern (e.g., portfolio_get_blog_post, portfolio_list_projects), using standard verbs and plural/singular nouns appropriately.
With 6 tools covering portfolio, blog posts, projects, and search, the set is well-scoped for a personal portfolio site—neither too few nor excessive.
The tool surface provides complete read-only access to all major parts of the portfolio: profile, blog posts (list+detail), projects (list+detail), and a full-text search. No obvious gaps exist for the intended use case.