MSPortfolio — MCP-Native Engineering Portfolio

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral detail by specifying the return shape: per-skill match with evidence and coverage. It does not discuss failure modes, but for a read-only comparison tool this is not a major gap.

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?

One efficient sentence that front-loads the action and outcome. Every word contributes meaning, with no filler or repetition of the tool name.

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 one-parameter read-only tool, the description conveys purpose, input meaning, and output shape reasonably well. It could be more explicit about what 'evidence' means, but the definition is sufficient for an agent to invoke the tool 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 coverage is 100%, and required_skills is documented in the schema. The description reinforces that the skills are the job's required skills, aligning the parameter with the tool's purpose, but it adds no additional syntax or formatting guidance.

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 'Compare' with clear resources: the owner's stack and a job's required skills. The output is also specified as per-skill match with evidence and coverage, which distinguishes it from sibling read tools like get_profile or get_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?

The intended use case is evident from the description: evaluating how well the owner's stack satisfies a job's required skills. However, it does not explicitly state when not to use it or name alternatives, leaving some inference to the agent.

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 and openWorldHint=false, and the description echoes these as 'Read-only, closed world.' It adds useful scope ('the owner's') and a content preview, but does not disclose return format, pagination, or other behavioral details. Since annotations cover the safety profile, this is adequate but not exceptional.

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 waste. It conveys the resource, content, and scope compactly, and every word contributes meaning.

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 parameterless, read-only tool with no output schema, the description gives enough context about what data is returned (mistakes, rationale, fixes, lessons). It does not mention whether the output is a list or how it is structured, but given the simplicity, the description is nearly complete.

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 zero parameters and schema description coverage is effectively 100%, so the description does not need to add parameter meaning. Under the baseline rule for 0 parameters, a score of 4 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 uses the specific verb 'Get' with a unique resource ('the owner's antipattern museum') and details the content: 'real engineering mistakes with why they were bad, how they were fixed, and the lesson.' This makes the purpose clear and distinct from most siblings, though it does not explicitly differentiate from overlapping tools like get_known_issues or get_experiments.

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 implies usage when one wants to learn from past engineering mistakes, but it does not explicitly state when to prefer this tool over siblings or provide any exclusions. The context is understandable but left to inference.

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 marking the operation as readOnlyHint and openWorldHint, the description adds modest value by indicating the data is recent and includes specific fields. It does not disclose details like result limits, ordering, or pagination, but the annotation coverage lowers the burden.

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 concise sentence that leads with the action and object, then enumerates the useful output fields. There is no redundant or filler content.

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 zero-parameter, read-only tool, the description sufficiently conveys what is retrieved and what fields are included. It could mention count or ordering, but that is not necessary for basic 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?

The tool has zero parameters, so the schema fully covers parameter semantics and the description has nothing to add. The baseline of 4 for a no-parameter tool 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 uses a specific verb ('Get') and a concrete resource ('recent Dev.to articles') and lists the returned attributes: reading time, tags, and links. This makes the tool's purpose unambiguous and clearly distinguishes it from siblings like verify_article.

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 does not state when to use this tool versus alternatives. It provides no context such as 'use this for recent articles, use verify_article for checking article authenticity,' so an agent receives no routing 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?

With readOnlyHint and openWorldHint annotations already present, the description still adds meaningful behavioral context: it notes the data is an 'hourly snapshot' (so not real-time) and limited to 'public repos'. This goes beyond the annotations without contradicting them.

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 with no filler: the first defines the tool and its key snapshot constraint, the second provides concrete usage cues. Every word 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?

For a zero-parameter, read-only tool with no output schema, the description covers the main concerns an agent needs: what it returns, its scope, its freshness, and when to ask for it. It does not describe exact output shape, but the simplicity of 'commit history' makes that less critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so the baseline is 4. The description does not attempt to describe parameters because none exist, and the empty schema is already 100% covered by the schema itself.

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 exact resource ('commit history across the owner's public repos') and the operation ('get recent'). It adds a distinctive detail ('hourly snapshot') and pairs it with concrete example questions, making it easy to tell apart from sibling tools like get_timeline or get_articles.

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 explicitly gives two query types it should be used for: 'what has he been building lately' and 'show the hardest bugs he has fixed'. It does not state when not to use it or name alternative sibling tools, so it falls just short of a 5.

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 and openWorldHint=false, and the description repeats these as 'Read-only, closed world.' It adds useful content-scope context (tagged NEW vs recurring) but does not disclose return shape, ordering, or pagination. The safety profile is covered by annotations, so this is acceptable but not exceptional.

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 with no filler: the first states the resource and content, the second gives concrete usage prompts, and the final tags state safety semantics. Everything earns its place and the core purpose is front-loaded.

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 parameterless, read-only tool, the description supplies sufficient content expectations and usage context. No output schema exists, but the description already tells the agent what kind of data to expect; no critical information for a correct call is missing.

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 has zero parameters, so there is no parameter ambiguity to resolve. Description adds no param-level detail because none is needed; the schema fully covers the empty parameter set.

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 ('Get') and resource ('the owner's engineering diary') and enumerates the content: incidents, root causes, fixes, guards, and pattern tags. The content detail makes it clearly distinguishable from sibling tools like get_known_issues or get_timeline.

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?

Explicitly names question types the tool is for: 'what broke and how did you fix it' and 'show your hardest debugging session'. It does not mention exclusions or alternatives, so it misses the top bar, but the use cases are clear and actionable.

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 readOnlyHint annotation already signals a safe read operation, and the description adds that results include examples and counterfactuals. However, it doesn't disclose return shape, size, or ordering. With annotations covering safety, a score of 3 fits: the description adds some meaningful context but not deep behavioral detail.

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. Every word earns its place by specifying the resource and two concrete content attributes.

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 parameterless, read-only tool, the description supplies sufficient information to understand what the tool returns. Some extra context about the format or length of the returned principles would round it out, but nothing critical is missing.

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 is empty with 0 parameters, so schema coverage is trivially 100%. The description needs no parameter explanation, and the baseline of 4 applies. It gives no misleading parameter hints.

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 uses a specific verb+resource ('Get engineering principles') and clarifies what the content includes ('real examples and A/B-style counterfactuals'). While it doesn't explicitly differentiate from siblings like get_antipatterns or get_articles, the resource noun 'engineering principles' is distinct enough.

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 vs alternatives. The context signals show no parameters, so its use is simple, but the description gives no conditions, exclusions, or references to sibling tools that might be alternatives for similar lookups.

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 and openWorldHint=false; the description adds useful behavior by noting that experiments include negative results and that verdict values are confirmed/refuted/partial. No contradiction with 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?

All sentences earn their place: the first defines scope and content, the second gives usage cues, and the third clarifies inclusion and read-only/closed-world behavior. No filler.

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 zero-parameter, read-only listing tool with no output schema, the description fully documents what each experiment contains, confirms read-only/closed-world behavior, and includes negative results. An agent can invoke and interpret it without further context.

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 has zero parameters, so the baseline is 4. Nothing further is needed or possible.

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 — 'Get the owner's engineering experiments' — and enumerates the fields returned: hypothesis, command, raw result and verdict. It clearly distinguishes this from sibling tools by focusing on experiments rather than articles, issues, or timeline entries.

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 explicitly maps to user intents: 'what did you measure' or 'show me an experiment you ran'. It does not name exclusions or alternatives, but the zero-parameter scope makes it reasonably self-contained.

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 description goes beyond the readOnlyHint and openWorldHint annotations by disclosing the not-found behavior: 'Returns a clear not-found with the available IDs if the ID does not match.' It also confirms 'Read-only, closed world,' matching the annotations and adding semantic clarity. This gives the agent useful expectations for failure cases.

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 sentences deliver everything needed with no filler. The main action is front-loaded, the returned fields are summarized, and the not-found behavior is stated compactly. 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?

For a single-parameter read-only detail tool with no output schema, the description is complete: it identifies the input, lists the expected fields, and explains the not-found case. There is no pagination, auth, or mutability concern that would require further elaboration.

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 already documents the single id parameter with an example and case-insensitivity, so schema coverage is 100%. The description repeats the 'ID' concept and example but adds no new parameter-level semantics. This aligns with the baseline 3 for high schema 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?

The description uses a specific verb and resource: 'Get the full detail of a single known issue by its ID.' It clearly narrows the scope to one issue and even names the kind of fields returned, distinguishing it from the sibling list tool get_known_issues. An agent can tell that this is the detail lookup and not a list or search operation.

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?

'By its ID' and 'Drills into one open problem' establish a clear context: use this when you already know the specific issue identifier and need full detail. It does not explicitly name alternatives or state when not to use it, so it falls short of a 5, but the context is clear enough for tool 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 and openWorldHint=false, and the description echoes both ('Read-only', 'closed world'). It adds modest context by characterizing the board as 'open debt' and listing fields, but adds little behavioral detail 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 compact at roughly three short sentences, front-loads the core operation, and every clause earns its place. The usage hint and read-only/closed-world clarification are each useful and not padded.

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 zero-parameter read-only tool with no output schema, the description fully covers what the tool returns, why an agent would call it, and its safety profile. Nothing essential is missing for 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?

The tool has zero parameters, so the schema carries no burden and the description needs to add no parameter detail. Per the baseline for 0-parameter tools, this is fully adequate.

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 and resource ('Get the owner's known-issues board') and describes the content ('open debt with status, temperature and deadlines'). This makes it clearly distinguishable from sibling tools like get_issue_detail and get_timeline, which focus on different slices of information.

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 explicitly provides usage context: 'Use it to answer what's still broken or what are you working on'. This gives clear situational guidance. However, it does not name any alternatives or state when not to use it, so it stops short of full routing 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?

The readOnlyHint annotation already establishes the safe, non-mutating nature of the tool. The description adds useful context about what the result contains (profile summary and nextSteps with contact channels, GitHub, MCP connect). No behavioral contradictions or hidden side effects are present.

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 carry the full purpose plus a usage directive. The most important information is front-loaded, and every phrase adds value without redundancy.

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 no parameters, no output schema, and read-only annotations, the description fully covers what the tool returns and when to invoke it. An agent has everything needed to correctly select and call this tool in the intended interview flow.

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 has zero parameters, so the schema fully defines the invocation surface. The description doesn't need to explain parameters, and the baseline of 4 applies because there is nothing missing for the agent to call it correctly.

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 identifies a specific verb ('Get'), a distinct resource ('the owner's professional profile summary'), and adds the supplementary 'nextSteps' content. It is clearly differentiated from sibling tools like get_projects or get_timeline, which target different resources.

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 explicitly states when to use the tool: 'Use it as the first tool in an interview.' This is strong contextual guidance. It does not mention alternatives or when not to use it, but given the unique profile resource, exclusions are less necessary.

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=true and openWorldHint=false, so the description does not need to restate safety. It adds some context by naming the return categories, but it does not clarify default behavior, pagination, limits, or how filtering interacts with the 'all' value.

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?

One concise, front-loaded sentence states the action, resource, key returned content, and the optional filter. There is no filler or redundant phrasing.

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 one-parameter, read-only retrieval tool, the description covers what is returned and the filter option. A small gap remains: it does not explicitly state the default when 'filter' is omitted, though the 'all' enum value makes that reasonably inferable.

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 100%, and the single 'filter' parameter already documents its enum values and meaning. The description's 'Optional filter by stack tag' essentially restates the schema without adding new semantic depth, so it earns the baseline but no more.

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: 'Get portfolio projects' with stack, highlights, and decision logs. It is clear and likely distinguishable from siblings like search_projects, though it does not explicitly name or contrast 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?

No guidance is provided about when to use get_projects versus search_projects or other sibling tools. There are no exclusions, prerequisites, or alternative-selection hints; the only usage hint is the optional stack-tag filter, which concerns parameter use rather than tool 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?

The readOnlyHint annotation covers the tool's safe read-only nature, and the 'Get' verb is consistent with it. However, the description adds no additional behavioral detail such as the timeline's contents, ordering, time range, or format. There is no contradiction with 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 filler or repetition. It is as concise as possible while naming the operation and resource.

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 zero-parameter read-only tool with no output schema, the description identifies what is returned but not its structure, scope, or relationship to sibling tools. It is adequate for invoking the tool, but an agent cannot fully anticipate the result or know when it is the best choice.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so parameter semantics are trivial. The description does not need to explain parameter meaning, and the zero-parameter baseline 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 uses a specific verb and resource, 'Get the engineering decision timeline', which is clear and distinguishes the tool from timeline-like siblings such as get_commit_history and get_diary. It does not explicitly contrast it with alternatives, 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?

There is no guidance about when to use this tool versus the sibling tools like get_commit_history, get_diary, or get_experiments. No conditions, prerequisites, or exclusions are mentioned, forcing the agent to infer usage from the name and description alone.

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 and openWorldHint, and the description repeats them. It adds value by disclosing the return shape: 'matched projects with a score and the fields that matched', which is not present in the annotations or schema.

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, front-loaded with purpose and usage. The only redundancy is repeating annotation flags ('Read-only, closed world'), which is minor and does not bloat the description.

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 single-parameter search tool with no output schema, the description covers the input, the behavior, the return value, and the usage context. Nothing critical is missing for an agent 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by specifying the fields the query searches across, helping the agent craft effective search terms.

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 uses a specific verb ('search') and resource ('portfolio projects'), and enumerates the searched fields (name, tagline, description, stack, decision-log rationale). It contrasts with a fixed stack-tag filter, which hints at differentiation from get_projects, but does not name the sibling tool explicitly.

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 clearly states when to use the tool: 'Use when a fixed stack-tag filter is too narrow', with concrete examples. It does not mention alternatives by name or state when not to use it, but the condition is explicit enough for an agent to decide.

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 declare readOnlyHint=true, and the description adds meaningful behavioral context: the tool returns latency percentiles per load and performs bottleneck analysis. It does not contradict the read-only hint, and for a simulation tool it adequately discloses what the agent should expect as output.

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 states the action, the resource, the scenario choices, and the return value with no filler. Every part of the 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 two fully schema-described parameters and no output schema, the description gives enough context: what the tool does, what scenarios it supports, and what it returns. It could mention output format or units, and it does not elaborate on simulation cost or limitations, but for the given complexity this is sufficient.

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% with both parameters documented and enum-restricted, so the schema already explains the parameters well. The description adds scenario examples and output context, but does not provide new parameter-level semantics beyond the schema.

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 uses a specific verb ('Simulate') and resource ('a project's architecture'), then scopes the behavior with concrete scenario examples and output types. It is clearly distinguishable from the sibling read/analysis tools, which are about fetching data or verifying claims rather than running a simulation.

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 implies when to use it: when you need to understand architectural behavior under load spike, node loss, cache cold, or LLM saturation. It gives the scenario categories and the type of answer produced, but it does not explicitly state when not to use it or mention alternatives; there is, however, no obvious sibling that competes for the same task.

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 and openWorldHint; the description adds concrete behavior: it fetches the live Dev.to API, returns specific fields, and gives an honest 'not found'. This goes beyond the annotation flags by explaining the actual network action and output semantics, though it omits failure-mode details like timeouts or rate 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?

The three sentences are front-loaded with the core purpose and outcome, followed by a concrete usage example and a brief safety note. There is minimal redundancy; the final annotation restatement is short and reinforces rather than bloats the description.

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 single-parameter tool with no output schema, the description covers purpose, parameter semantics, return behavior, and safety profile. It tells the agent exactly what to expect (found article fields or 'not found') and is sufficiently complete for 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 100%, with query already defined as 'Article title fragment or keyword, e.g. "agent memory" or an exact title.' The description reinforces the query's matching role but adds no new syntax or format details beyond the schema, so the baseline of 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 ('Verify'), a clear resource ('an article against the primary source (Dev.to)'), and the expected outcome (real title/date/reactions/url or 'not found'). The article-specific focus clearly distinguishes it from sibling tools like verify_claim, verify_package, and verify_repo.

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 explicit usage context with 'Use it to ground claims like "he wrote about agent memory" in the platform's data instead of the portfolio's own words.' It does not name alternatives or give when-not-to-use conditions, but the use case is unambiguous enough for an agent to select it appropriately.

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 description adds meaningful behavioral context beyond the readOnlyHint annotation: it is deterministic, returns evidence records with source paths, and provides a supported verdict. It does not describe the case when no evidence supports the claim, but the core behavior is clearly disclosed.

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; the first sentence states the core function and return shape, the second gives usage guidance. No filler or repetition of schema details.

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 one parameter, no output schema, and a read-only annotation, the description explains what the tool returns, the scope of the claim, and when to use it. It is sufficient for an agent to correctly select and invoke the tool, with only minor omissions around unsupported claims.

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%, so the schema already documents the single 'claim' parameter. The description adds that the claim is 'about the owner', which is useful but does not materially expand the parameter semantics beyond the schema's example.

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 ('Ground'), a clear resource ('the portfolio's data'), and enumerates the exact sources involved (profile, projects, principles, etc.). It effectively differentiates from sibling tools by scoping claims to 'about the owner', making it distinct from verify_article, verify_package, and verify_repo.

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 explicitly provides when to use the tool: 'before asserting a fact about the owner, or to check what an answer was based on.' It does not explicitly name sibling alternatives or exclusions, but the portfolio-specific scope strongly implies when not to use it.

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 and openWorldHint, and the description adds valuable context beyond those: the honest 'not found' behavior, the network-fetch nature, and the specific data points consulted. No contradiction with 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?

Three dense sentences front-load the purpose and scope, with each clause adding useful information. The final 'Read-only, open world (network fetch)' partially repeats the annotations, but it also adds the network detail, making it acceptable rather than wasteful.

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 description enumerates the key output dimensions (existence, latest version, publish date, description, license, maintainers, owner) and the not-found behavior, effectively compensating for the absence of an output schema. For a simple one-parameter tool, this fully equips an agent 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?

The input schema already documents the only parameter with 100% coverage, including an example and lowercase requirement. The description adds no additional parameter-specific syntax or formatting details, so the baseline of 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 starts with a specific verb, 'Verify', names the exact resource ('npm package' against registry.npmjs.org), and enumerates the concrete checks performed. This clearly distinguishes it from sibling tools like verify_repo and verify_claim, which target different artifact types.

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?

Explicitly instructs when to use it: to ground claims like 'he published an npm package' in registry data instead of the portfolio's. It provides clear context but does not explicitly name an alternative sibling tool or state when not to use it, so it stops short of the highest tier.

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?

Beyond the annotations (readOnlyHint, openWorldHint), the description explains what the open-world operation actually does: it performs a network fetch, retrieves specific metadata fields (exists, language, description, topics, stars, last push), conditionally cross-checks against portfolio records, and optionally returns README text. This adds substantial behavioral context and 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 description is compact and front-loaded with the core purpose. Each sentence adds something: the verification process, the readme option, and the concrete usage scenario. The first sentence is slightly dense with parenthetical details, but there is no redundant filler beyond briefly restating the annotations.

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 compensates by enumerating the metadata fields returned and describing the README behavior. It also covers the cross-check condition and the intended use case. It doesn't specify error handling or the exact shape of a repo-not-found result, but the coverage is strong enough for an agent to invoke the tool 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 already 100%, setting a baseline of 3. The description goes further by clarifying that repo can be a bare name with owner defaulting to ManSio, a full owner/name pair, or a GitHub URL — details not present in the schema. It also adds the ~1200 character README truncation behavior for readme=true.

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: 'Verify a GitHub repository against the primary source'. It then details the exact mechanism — fetching metadata from the GitHub API and cross-checking it with the portfolio record — and distinguishes itself from generic claim-verification tools by focusing on repository facts. The readme:true behavior reinforces the unique scope.

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 explicit usage direction: 'Use it to ground claims like "the repo is Python" or "he maintains mscodebase-intelligence" with live data instead of trusting the claim.' This clearly communicates when to invoke the tool. It does not explicitly mention when not to use it or name sibling alternatives such as verify_claim, but the repo-specific context makes the intended scope clear.

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