Portfolio MCP | Benjamin Nikolajew

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, idempotent, non-destructive, and open-world, so the safety profile is settled. The description adds real value beyond that: HTML extraction, the derivation of a bounded query from an approved URL path, and pagination over changelog rows with accurate matching counts. It omits any note on rate limits or failure behavior for non-approved domains.

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?

Three tight sentences, front-loaded with what the tool returns and followed by input modality and pagination. Little waste, though 'truthful matching counts' is vague phrasing that could be more concrete.

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?

An output schema exists, so return values need no prose, and annotations handle the safety story. Still, for a seven-parameter, multi-modal tool, the unaddressed domains and maxPages parameters leave a real gap an agent would hit when narrowing a fetch.

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 carry the load, and it only partly does: it explains the url/urls/query alternatives and the rowLimit/rowOffset pagination intent. It says nothing about domains (allowlist filtering) or maxPages (crawl breadth cap), leaving two of seven parameters undifferentiated from their bare types.

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?

States a specific verb pair (fetches and extracts) plus the resource (approved first-party or official-domain HTML pages) and the purpose (page-level evidence). That distinguishes it reasonably from search_first_party_context, though no sibling is named explicitly, so the boundary with get_first_party_context is left to inference.

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 spends its guidance on input modality (query vs urls vs legacy url) rather than when to choose this tool over search_first_party_context, get_first_party_context, or get_changelog. No when-not conditions or prerequisites are given, so an agent still cannot confidently route between the several context-fetching siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that the payload is 'condensed' (as opposed to a full profile) and enumerates what it includes, which is useful context, but it says nothing about size limits, whether defaults are applied, or how the 'next-tool prompts' behave.

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?

A single front-loaded sentence that states the return payload immediately, with no filler. The trailing 'proactive next-tool prompts' is somewhat jargon-heavy and slightly muddies the otherwise crisp enumeration.

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?

An output schema exists, so return values need not be re-explained, and annotations cover safety. The remaining gaps are the undocumented optional parameters and the lack of differentiation among many similar profile siblings, which leaves an agent guessing when this is the right call.

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 carries the full burden for three parameters, yet it never mentions includeVisual, conciseSkillLimit, or includeAvailability. 'Concise skills' and 'profile image' loosely echo two params but do not explain defaults, ranges (3–10 for conciseSkillLimit), or what omitting a flag changes.

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 gives a specific verb ('Returns') and names the payload contents (current role, concise skills, profile image, email CTA, next-tool prompts), so the agent knows this is a condensed profile-summary endpoint. However, it never distinguishes this from close siblings like get_professional_profile, get_profile_fact_pack, or get_contact_email, so the boundary is left implicit.

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?

There is no statement of when to call this versus the many other profile-related tools (get_professional_profile, get_profile_fact_pack, get_contact_email). The phrase 'proactive next-tool prompts' faintly hints that this is an entry point, but no explicit routing or exclusion is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds that content is 'grounded' and includes limits and canonical links, which is modest extra context but not rich behavioral disclosure.

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?

A single front-loaded sentence that packs the return content without filler. It is slightly dense with stacked noun phrases but wastes nothing.

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 an output schema present and zero parameters, the description need not explain return shape, and it adequately conveys the kind of content delivered. What is missing is routing context relative to sibling retrieval tools, which keeps it short of 5.

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?

Zero parameters, so the schema-vs-description comparison is moot and the baseline is 4. The description correctly implies a no-argument retrieval and adds no misleading parameter expectations.

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?

States a specific verb (Returns) and enumerates the resource content: Portfolio Agent/MCP explainer content, capability lanes, limits, and canonical links. An agent can distinguish this as an explainer/metadata endpoint, though 'capability lanes' is domain jargon that assumes prior knowledge.

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?

No guidance on when to call this versus siblings like fetch_curated_page_context, get_first_party_context, or search_first_party_context. There is no trigger condition, prerequisite, or exclusion stated, leaving the agent to guess when this explainer is relevant.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds meaningful context beyond that: the exact asset categories returned, the presence of a ZIP download for the complete set, and the optional section filtering.

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?

Two sentences, zero waste, with the core return content front-loaded and the filtering option following. 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?

With an output schema present and rich annotations, the description needn't explain return values or safety. It adequately covers what the kit contains and how to filter, though it could clarify the default all-sections behavior and the relationship to the download-assets sibling.

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 coverage is 0%, so the description must compensate. It does list all six enum values in prose ('identity, logo, color, typography, icons, or imagery') and marks the filter as optional, but it does not explain the default behavior when section is omitted or what each section contains.

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?

States a specific verb and resource ('Returns the first-party Nikolajew Design brand identity') and enumerates the asset types included. It is clearly distinguishable from profile/career siblings, but does not explicitly differentiate itself from the related get_download_assets tool despite mentioning a ZIP download.

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?

Provides use-case context ('for style decks, webpages, cards & documents') but never states when to prefer this over siblings like get_download_assets or get_download_documents, nor any exclusions. Usage is implied rather than guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is fully covered. The description adds nothing behavioral beyond a field list: it doesn't say what 'documented' means, whether results are paginated, how results are ordered, or whether an empty result is normal — all relevant to a multi-result query tool.

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is partly a symptom of under-specification rather than disciplined editing.

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?

An output schema exists, so explaining return fields is redundant, and that is nearly all the description does. With three undocumented parameters, no usage guidance, and an optional-filter surface, the definition leaves an agent without what it needs to pick filters or decide when this tool is the right one.

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?

All three parameters (limit, query, includeSkills) have 0% schema description coverage, so the description must compensate and does not. 'Skills focus' only faintly hints at includeSkills, and query semantics (what fields are searched, the minLength 2 requirement) and the limit default/cap are never addressed.

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?

States a specific resource (certificates) and enumerates the fields returned (issuer, credential ID, verification URL, skills focus), which distinguishes it from get_career_education and get_career_timeline. It never explicitly says how it differs from those siblings, though the resource noun does most of the work.

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 no indication of when to call this versus get_career_education, get_career_timeline, or get_professional_profile. There are no prerequisites, no exclusions, and no mention of the filter/pagination options an agent would need to choose it deliberately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds that entries carry program focus and source links, but says nothing about the default limit of 6, the max of 10, whether results are paginated, or how the query string matches.

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?

A single front-loaded sentence with no filler; the payload contents come first. It is efficient, though the brevity is partly under-specification rather than true concision.

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?

An output schema exists, so return values need not be explained, and the annotations cover safety. The remaining gap is the undocumented query/limit semantics and the lack of routing versus the career-* siblings, leaving the description only minimally adequate.

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 is the only place parameter meaning could be conveyed — yet neither 'limit' nor 'query' is mentioned. An agent cannot tell whether query matches on institution, program name, or free text.

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?

States a specific verb and resource ('Returns education history entries') plus the payload shape (program focus and source links). It does not distinguish itself from close siblings such as get_career_certificates or get_career_timeline, so an agent must infer the boundary.

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?

There is no when-to-use guidance, no exclusions, and no mention of the obvious alternatives (certificates, timeline, role detail) that could also surface career-education data. The agent is left to guess which sibling to call.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds the useful detail that data comes from first-party employment history, but says nothing about what happens when only one role is supplied, what detailLevel changes in the output, or any coverage/fallback behavior.

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?

A single front-loaded sentence with no filler; the object of the comparison and the data source are stated immediately. It is efficient, though its brevity contributes to the semantic gaps noted elsewhere.

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?

An output schema exists, so return shape needn't be described, but for a six-parameter tool with zero schema documentation the description should explain how left/right roles and companies combine, what 'query' does, and what each detailLevel yields. None of that is present, leaving invocation ambiguous despite annotated safety.

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% across six parameters, so the description carries the full burden. It implies a left/right pairing of roles and companies but never explains the free-text 'query' parameter, the summary/detailed/full detailLevel enum, or the fact that all parameters are optional (required: 0), which materially changes how the tool should be invoked.

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 (returns a side-by-side comparison) and a specific resource (two career roles/companies) backed by a stated data source (first-party employment history). It implicitly contrasts with get_career_role_detail's single-role view, but never names the sibling, so differentiation must be inferred.

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?

There is no guidance on when to use this instead of get_career_role_detail, get_career_timeline, or search_first_party_context, and no note on prerequisites such as whether both roles must exist or whether companies are optional. The only hint of usage is the word 'comparison' itself, which leaves the agent to guess.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful nuance of 'richer factual context' and 'single match' (implying a narrowing lookup), but says nothing about how missing or ambiguous role/company inputs are resolved or what depth each detailLevel produces.

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?

A single sentence, front-loaded with the verb and resource, with the 'deep-dive' qualifier doing real routing work. It is lean, though the brevity is partly achieved by omitting parameter meaning rather than by tight editing.

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?

An output schema exists, so return format need not be re-explained, and all four parameters are optional. Still, with 0% schema description coverage the agent is left guessing about `query` and how `role`, `company`, and `detailLevel` interact, which is a meaningful gap for a lookup tool.

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 carry the parameter burden. It only gestures at 'role/company' and 'richer factual context'; it never explains the 'query' parameter, whether role and company are jointly required, or what summary/detailed/full change in practice beyond the enum labels.

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 opens with a specific verb and resource ('Returns a single role/company experience match') and adds the qualifier 'richer factual context for deep-dive career questions'. That distinguishes it from get_career_role_comparison and get_career_timeline implicitly, though it never names those siblings.

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 phrase 'for deep-dive career questions' implies when to reach for this tool, but there is no explicit when-not guidance, no prerequisite, and no named alternative such as get_career_role_comparison or get_career_timeline when a broad or comparative view is needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the genuinely useful trait that results carry citations, but says nothing about ordering, coverage window, or what a timeline entry looks like beyond the output schema's implication.

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?

A single front-loaded sentence with no filler. Efficient, though the brevity is part of the reason other dimensions are thin rather than a virtue in itself.

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 four optional parameters at 0% schema documentation and a boolean (includeEducation) whose effect is never stated, the definition is too sparse for an agent to call confidently. The output schema covers return shape, but nothing explains default limit=10/max 20 or what query filtering actually matches.

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 four parameters. It only gestures at two of them (query, company), never explaining what query matches (role? company? skill?) or what the difference between query and company is, and it omits limit and includeEducation entirely.

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?

"Returns citation-backed career milestones" names a specific verb and resource, and "citation-backed" distinguishes the output from plain career data. It does not, however, differentiate itself from the many career siblings (get_career_education, get_career_role_detail, get_career_certificates), so the agent must infer that this is a chronological milestone list.

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 phrase "optional query/company filtering" hints at use cases but never states when to choose this over get_career_role_detail or get_career_education. No when-not conditions or alternatives are given anywhere in the one-sentence description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds genuinely useful behavior beyond that: the dataset is 'complete generated release data' and pagination cursors are 'stable' for complete notes. It does not mention ordering, default page size, or what happens when a cursor expires.

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?

Two tightly packed sentences with the core purpose front-loaded and no filler. The second sentence is dense with capability keywords but each maps to an actual parameter family, so little is wasted.

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?

An output schema exists, so return shape needn't be explained, and annotations cover safety. For a read-only paginated list tool, the description plus those structured fields give an agent enough to call it correctly; the remaining gaps are parameter fine points rather than blockers.

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% across 9 parameters, so the description carries the burden and it partially does: it names the filter families (version, date, category, query) and the cursor. But it never disambiguates 'version' from 'afterVersion'/'throughVersion', nor specifies date formats or the role of 'limit', leaving roughly half the parameters semantically ambiguous.

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?

States a specific verb and resource (returns the first-party Portfolio release history) plus the source dataset, which is more than a restatement of the name. It doesn't explicitly distinguish itself from nearby siblings like search_first_party_context or fetch_curated_page_context, so an agent must infer that this is the versioned release-notes endpoint.

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 phrase 'supports exact/latest/all versions, bounded ... filters, and stable cursor pagination' implies the available query modes, which is real usage context. However, there is no statement of when to prefer this tool over the context/search siblings, nor any exclusion or prerequisite guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that by clarifying the capability boundary — no message submission is possible and visitors must use their own email app or the site form — which prevents an agent from misusing the result.

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?

Two short sentences, front-loaded with the core purpose, with no filler. The capability caveat is compact and earns its place, though it could have been folded more tightly into the first sentence.

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 an output schema documenting the returned fields and annotations covering safety, the description only needs to convey purpose and constraints, which it does. The one gap is not naming which contact channel (email) is returned, but the output schema fills that.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is trivially complete at 100% coverage.

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?

"Returns canonical contact information" gives a verb and a resource, but the resource is vaguer than the tool name implies (email vs. generic "contact information"). It never distinguishes this from sibling lookups like get_social_profiles or get_professional_profile, so an agent gets only a rough sense of what comes back.

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 second sentence establishes a clear when-not-to-use boundary: this tool cannot send messages, so an agent should not invoke it to contact anyone. However, there is no positive guidance on when to pick this over the many sibling context-fetching tools, leaving usage only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the useful detail that it returns multiple link types (download + profile), but no pagination, rate-limit, or availability information beyond that.

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?

A single front-loaded sentence with no filler. It is efficient, though the density of stacked link types makes it slightly harder to parse than a clean subject-verb-object statement.

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?

An output schema exists, so return-value detail is not required, and annotations cover safety. The remaining gaps are the undocumented includeWebLinks parameter and the unresolved overlap with get_download_documents, which leave the agent's selection decision under-informed.

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% and the sole parameter includeWebLinks is undocumented in both schema and description. The mention of "online profile links" loosely implies web links exist, but it does not explain the boolean toggle, its default, or what happens when it is false.

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?

States a concrete verb ("Returns") and specific resources: resume/CV download links, mini-portfolio download links, and online profile links. However, it never distinguishes itself from the sibling get_download_documents, which sounds near-identical, so the agent cannot confidently tell them apart without opening schemas.

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?

No when-to-use or when-not-to-use guidance is given, and the closest sibling (get_download_documents) is not mentioned or excluded. The phrase "for action-ready cards" hints at a UI context but does not tell an agent when this tool is the right choice over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds only that the returned documents are first-party and include grounded file metadata for supportive cards; it does not disclose permissions, rate limits, or other behavioral details beyond 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 description is a single, front-loaded sentence with no redundant or filler content. Every phrase contributes to identifying the returned resource and its metadata.

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 zero parameters, rich annotations, and an existing output schema, the description is largely complete: it identifies the returned documents and metadata purpose. The main missing element is differentiation from the sibling get_download_assets, which would help an agent choose correctly.

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 tool takes zero parameters, so there are no parameter semantics to explain. This is the appropriate baseline for a no-argument tool.

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 gives a clear verb and resource: it returns first-party resume and mini-portfolio download documents with grounded file metadata. It is specific enough to understand the output type, but it does not distinguish this tool from the sibling get_download_assets, which likely overlaps in purpose.

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 offers no explicit guidance on when to use this tool versus alternatives, nor does it mention the closely related get_download_assets sibling. The phrase 'for supportive cards' hints at a UI context but does not clarify agent-facing selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, closed-world, and non-destructive behavior, so the safety profile is covered. The description adds only that results are 'cited' sections, but says nothing about pagination, limit behavior, topic filtering, or how query and topics interact.

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 a single front-loaded sentence with no filler. It is efficient, though it is arguably too terse given the tool's breadth and its three undocumented parameters.

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?

An output schema exists, so return structure need not be explained. However, for a retrieval tool with three parameters at 0% coverage and strong overlap with search_first_party_context, the description omits parameter behavior, query/topic semantics, and sibling differentiation.

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 schema has three parameters (limit, query, topics) with 0% description coverage, and the description mentions none of them. It does not explain what query matches, how topics constrain results, or what the default or maximum limit means.

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 ('Returns') and resource ('cited first-party sections') and enumerates the domains covered. However, it does not distinguish this aggregate fetch from the sibling search_first_party_context or explain how the two differ, leaving an agent unsure which to call.

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?

There is no guidance on when to use this tool versus search_first_party_context, fetch_curated_page_context, or the many domain-specific getters. The list of covered sections implies broad context gathering but provides no conditions, exclusions, or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive behavior, so the description appropriately adds value by disclosing that the catalog is bounded, the random track is cryptographically selected, and shortest-track ties are included. It also mentions included production details, AI-involvement declarations, links, and citations.

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 compact and front-loads the return modes. It is a dense single sentence, but nearly every clause adds useful information about what the tool returns.

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?

An output schema exists and annotations cover the safety profile, so return-value detail is not strictly required in the description. However, for a four-parameter tool with 0% schema description coverage, the description is incomplete about how the parameters select modes and interact.

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% for four parameters, so the description must compensate. It vaguely implies album/track selection and random-track behavior but never names albumId, trackId, randomTrack, or excludeTrackIds, and gives no explanation of exclusions, precedence, or the maxItems limit.

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 that the tool returns music resources: a catalog, a selected album or track, or a random track. It specifies the resource domain and output modes, making it distinguishable from unrelated sibling tools, though it does not name a music-related alternative because none exists.

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 enumerates return modes but does not explain when to use each mode, how parameters select them, or any prerequisites. There is no explicit guidance such as using albumId for album selection or randomTrack for random selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds the useful behavioral claim that answers are 'grounded' and that a direct link to the full policy is always included, but says nothing about what happens when no match is found, pagination, or result shape beyond the link.

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?

A single front-loaded sentence that leads with the verb and resource, then enumerates coverage and closes with the return-value promise. The colon list is dense but every element conveys scope; no filler sentences.

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 read-only retrieval tool with an output schema and full annotation coverage, the description covers purpose and the guaranteed return artifact (policy link) adequately. The material gap is the complete absence of parameter guidance across three undocumented inputs, which an agent needs in order to call it correctly.

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% for all three parameters, so the description must carry the burden — but it never mentions 'query', 'limit', or how 'topics' is structured. The topic enumeration ('what is collected, how prompts are processed, where data is sent, providers, security, retention, rights') is a partial hint at valid topic values, which is the only substantive parameter guidance offered and leaves limit/query semantics unexplained.

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 and resource ('Returns grounded privacy and data-handling answers') and enumerates the scope of the corpus (nikolajewdesign.ca, Portfolio Agent, WebMCP, agent integrations) plus the covered question areas. An agent can tell this is a privacy/data-handling Q&A retrieval tool, though it never names a sibling like search_first_party_context to distinguish itself from general context search.

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?

Usage is only implied: the enumerated topics (what is collected, prompts, retention, rights) signal the kinds of questions to route here, but there is no explicit when-to-use statement, no exclusions, and no mention of when to prefer search_first_party_context or get_first_party_context instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by saying results are deterministic and include provenance, which is not present in the annotations and helps set expectations about repeatability and traceability.

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?

It is a single front-loaded sentence with no filler. The returned categories are listed compactly, and 'with provenance' is a useful qualifier rather than padding.

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?

Because an output schema exists and annotations are rich, the description need not explain return values or safety. Still, given the unusually crowded sibling set of profile, contact, fact-pack, and capability tools, the description should do more to clarify what this aggregate tool includes that the narrower tools do not.

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 tool takes zero parameters, so there are no parameter semantics to explain. The baseline for a no-parameter tool is 4, and there is no schema complexity the description needs to compensate for.

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 several content categories (profile, contact, process, personality, capability-limit signals) and says it returns them with provenance, so the general purpose is inferable. However, 'signals' is vague, the professional-profile framing comes mostly from the title, and it does not distinguish this tool from overlapping siblings such as get_profile_fact_pack, get_contact_email, or get_agent_capabilities.

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?

There is no statement of when to use this tool, when not to use it, or which sibling to prefer for narrower needs. An agent must guess between this aggregate profile tool and the many more specific profile/contact/capability tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already establish a safe read-only, idempotent, non-destructive profile with openWorldHint=false. The description adds useful behavioral detail beyond the annotations by explaining that unknown topics return 0 facts, a not-covered note, and knownTopics, which helps an agent interpret empty or partial results.

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 tight sentences: the first front-loads the return scope and covered categories, and the second explains the unknown-topic edge case. There is no redundant or wasted language.

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?

The output schema exists, so return values do not need full explanation here, and the annotations cover safety behavior. However, the description does not address the otherwise undocumented query and limit parameters or sibling selection, leaving meaningful gaps for an agent to infer before calling the tool.

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 schema has 0% description coverage across three parameters, so the description needs to carry the burden. It indirectly references topics by mentioning unknown topics and knownTopics, but it does not explain the roles of query or limit, nor how topics and query interact, leaving most parameter semantics undocumented.

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 and resource: it returns grounded long-tail profile facts from first-party resume data, and it lists the covered categories (qualifications, strengths, availability, AI usage, web capability, tool stack, context). This is clear, but it does not differentiate the tool from sibling profile/context tools, so it stops short of a 5.

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?

Usage is only implied by the phrase 'long-tail profile facts' and the topic-oriented scope. There is no explicit guidance about when to use this instead of siblings such as get_about_resume, get_first_party_context, or search_first_party_context, and no exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations already covering read-only, idempotent, and non-destructive behavior, the description adds useful context: default returns 3-5 ranked images per project, limitProjects caps projects at three, and unanchored requests return clarification. It does not disclose auth or rate limits, but the added behavioral traits are substantive.

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?

Two tightly written sentences with zero waste. The primary return behavior is front-loaded, followed by the edge-case clarification behavior, making it easy to scan.

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?

An output schema and safety annotations reduce the burden, so return values and safety profile need not be explained. However, with six parameters and 0% schema description coverage, the description is incomplete for parameter semantics and does not fully help an agent understand all inputs.

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% for six parameters, so the description must compensate. It only implicitly clarifies limitProjects (up to three) and imagesPerProject (3-5 images); it says nothing about query, aiFilter, category, or projectSlug, leaving most parameters undocumented.

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 ('Returns') and resource ('thumbnail plus 3-5 ranked artwork images') scoped to a project or category. It clearly distinguishes default behavior from the limitProjects variant, though it does not explicitly contrast with sibling tools like get_project_by_slug or list_portfolio_projects.

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?

It gives clear usage context: use for a named project or category; unanchored requests yield a clarification rather than an arbitrary project. This provides a when-to-use and a when-not condition, but it does not name alternative tools for cases like listing all projects or fetching project metadata.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds that the response is fully structured and citation-bearing, which is real value, but says nothing about what happens on an unknown slug or how 'ranked' highlights are ordered/truncated.

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?

A single front-loaded sentence that packs the return contents without filler. It is efficient, though the extreme density means some of the listed payload elements are asserted rather than explained.

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?

An output schema exists, so return-value documentation is legitimately omitted, and the description's payload summary plus annotations cover the read-only contract. However, with a 0%-covered 5-parameter schema, the missing explanation of focusQuery and the visual-scaling flags leaves a real behavioral gap for an agent composing the call.

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% across five parameters, so the description carries the full burden. It only loosely gestures at three of them ('ranked visual highlights' for includeVisuals/maxVisuals, 'optional case-study signals' for includeCaseSignals) and never mentions focusQuery at all, nor defaults (5), bounds (1-8), or the visual-ranking semantics.

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?

States a specific verb and resource ('Returns full structured portfolio project data by slug') and enumerates the payload's distinctive contents (provenance, ranked visuals, case-study signals). An agent can distinguish it from list_portfolio_projects or get_project_followup_detail, though the description never explicitly names those alternatives.

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?

There is no guidance on when to reach for this tool versus the many sibling project tools (get_project_artwork_gallery, get_project_followup_detail, search_project_notes), nor any prerequisite such as where a valid slug comes from. Usage is only implied by the word 'slug'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile needs no restating. The description adds some behavior (returns exactly one best match, includes citation-backed signals), but omits how matching is decided, what happens on no-match, and whether query and projectSlug conflict.

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?

A single front-loaded sentence with no filler, and the core return shape comes first. It is efficient, though the brevity is partly the cause of the documentation gaps rather than a virtue.

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?

An output schema exists, so return values needn't be explained. But a 6-parameter tool with zero schema coverage and no guidance on query vs projectSlug precedence, focus enum effects, or sibling differentiation leaves the agent guessing on invocation.

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% across 6 parameters, so the description carries the full burden. It only obliquely gestures at three of them (focus via 'focus highlights', includeVisuals/maxVisualsPerResult via 'visual context', includeCaseSignals via 'citation-backed signals'), and says nothing about query, projectSlug, enum values, or which identifier takes precedence.

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?

It names a specific outcome (return one best-matched project deep-dive with highlights, visuals, and citations), which is more than a restated title. But it never distinguishes itself from close siblings like get_project_by_slug, search_project_notes, or get_project_artwork_gallery, so an agent can't tell when this specific 'follow-up' variant applies.

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 phrase 'for follow-up questions' implies a usage context, suggesting this is a second-turn refinement tool rather than a first lookup. However, no alternatives are named, no conditions or exclusions are given, and it never says what to do if no project matches.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds useful output context (handles, icon keys, citation-backed metadata) but says nothing about how the optional network/email filters affect results or about response shape limits.

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?

A single well-formed sentence with no filler, front-loading the return content. It is appropriately sized but leaves necessary detail unstated rather than being verbose.

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?

An output schema exists, so return values need not be explained, but the three input parameters are undocumented in both schema and description, and there is no usage guidance. For a tool whose parameters meaningfully change results, the description is too thin to guide correct invocation.

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% across three parameters (networks, includeEmail, includeProfileReferences), and the description mentions none of them. An agent learns the output fields but not what the inputs control, how to restrict networks, or what the include toggles suppress.

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?

States a clear verb (returns) and resource (social profile links), and enumerates what the response contains: handles, icon keys, and citation-backed metadata. It is distinguishable from siblings like get_contact_email or get_brand_kit, though it does not explicitly contrast with any of them.

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?

Provides no guidance on when to use this tool versus siblings such as get_contact_email or get_professional_profile, and no indication of when not to use it. Usage is only inferable from the tool name and one-sentence purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this is read-only, idempotent, non-destructive, and closed-world. The description adds useful dataset context such as the fixed count, curation, and music routing, but does not explain pagination, limit behavior, or how the filters affect results.

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 definition is front-loaded and compact: the first sentence states what is returned and the second routes music queries elsewhere. There is little waste, though the sparse treatment of filter parameters limits usefulness.

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 read-only list tool with 11 undocumented parameters, the description is too thin. The output schema can cover return values, but the description should do more to explain the filter and inclusion parameters that materially change behavior.

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?

There are 11 parameters and 0% schema description coverage, so the description must do the explaining. It vaguely refers to optional filters, visuals, and randomized discovery, but leaves query, category, aiFilter enum values, limit, excludeSlugs, onPublicGrid, includeSummary, includeCaseSignals, and maxVisualsPerProject undocumented.

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 resource and scope: 21 curated portfolio entries, including 20 public design case studies plus SAE Engineering. It distinguishes the tool from get_music explicitly, but does not clarify how it relates to detail-oriented siblings such as get_project_by_slug or get_project_artwork_gallery.

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?

It gives one clear alternative for music via get_music, but does not say when to use this list tool versus get_project_by_slug, get_project_artwork_gallery, or search_project_notes. Usage is only implied by phrases like 'optional filters' and 'randomized discovery.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, destructiveHint=false, and idempotentHint=false. The description adds meaningful behavior beyond that: it explains the allowlist constraint and the no-network fallback that returns a truthful zero-result response when runtime context is missing.

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?

Two tightly written sentences, with the core scope and runtime condition front-loaded. No sentence is wasted.

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?

The output schema and annotations reduce what the description must carry, and the description covers the important runtime fallback behavior. It remains incomplete for a three-parameter search tool because query, limit, and domains are undocumented in both the schema and the description.

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% for three parameters (query, limit, domains). The description does not explain what the query string does, how limit is applied, or how the domains array interacts with the approved-domain allowlist, leaving parameter semantics almost entirely undocumented.

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 gives a specific verb ('Searches') and resource scope ('approved owned or official public domains'), which distinguishes it from first-party search siblings. It does not explicitly name alternatives like search_first_party_context, so it falls short of a 5.

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?

It provides a runtime condition: use only when request-scoped external-search support is available, otherwise a zero-result response is returned. However, it gives no guidance on when to prefer this over sibling search tools such as search_first_party_context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds one meaningful trait beyond that — results are 'cited', i.e. they carry provenance — but says nothing about ranking, matching behavior, or what happens when no topics match.

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?

A single front-loaded sentence with no filler; the verb and resource lead and the domain list follows. It is efficient, though the comma-spliced domain list gets slightly listy without structure.

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?

An output schema and rich annotations relieve the description of explaining return values and safety, and the domain list covers scope. What remains missing is the disambiguation from heavily overlapping siblings and any documentation of the three undescribed parameters, which is a meaningful shortfall for a search tool in a crowded namespace.

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% across three parameters, so the description carries the full burden and largely fails: query syntax, what the limit caps, and especially what values belong in `topics` (free strings? these domain names?) are never addressed. The enumerated domains loosely hint at valid topics values, which is the only partial compensation.

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?

States a specific verb ('Searches') plus the resource ('cited first-party context') and enumerates the topical domains covered (career, projects, Ephemera Digital Collection, donations, Portfolio MCP setup, contact facts). An agent can tell what it returns, but the description never contrasts it with the obviously overlapping siblings get_first_party_context, search_project_notes, and fetch_curated_page_context.

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?

Usage is only implied through the topical enumeration — the agent can infer when the tool is relevant but is given no when-to-use rule, no exclusions, and no named alternative. With three sibling search/context tools in the list, the absence of routing guidance is a real gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds that results are ranked and include citation URLs and visual highlights, but much of this is return-value detail already implied by the output schema rather than new behavioral context.

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?

A single dense sentence with no wasted words, and the verb and scope are front-loaded. It is tight, though its brevity is partly why parameter and usage detail are missing.

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 an 8-parameter tool with an enum filter and multiple boolean toggles at 0% schema coverage, the description is far too thin. It omits any explanation of the filter semantics, pagination/limit behavior, or exclusion logic an agent needs to invoke it correctly.

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% across 8 parameters, so the description must carry the burden and largely fails. It only obliquely gestures at includeVisuals ('visual highlights') and includeCaseSignals ('case-study signals'); query, limit, aiFilter (7-valued enum), category, excludeSlugs, and maxVisualsPerResult are all left unexplained.

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?

States a specific verb and resource ('Searches project narrative fields') and describes the ranked excerpt result shape. It distinguishes itself as a search tool, though it doesn't explicitly differentiate from sibling search tools like search_first_party_context or search_allowed_external_domains.

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?

There is no guidance on when to use this versus the many sibling tools (search_first_party_context, get_project_by_slug, fetch_curated_page_context). The phrase 'optional case-study signals' hints at a toggle but never states a use case or exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.